git.notmuchmail.org Git - notmuch/blob - lib/notmuch-private.h

   1 /* notmuch-private.h - Internal interfaces for notmuch.
   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 #ifndef NOTMUCH_PRIVATE_H
  22 #define NOTMUCH_PRIVATE_H
  23
  24 #ifndef _GNU_SOURCE
  25 #define _GNU_SOURCE /* For getline and asprintf */
  26 #endif
  27 #include <stdio.h>
  28
  29 #include "compat.h"
  30
  31 #include "notmuch.h"
  32
  33 NOTMUCH_BEGIN_DECLS
  34
  35 #include <stdlib.h>
  36 #include <stdarg.h>
  37 #include <sys/types.h>
  38 #include <sys/stat.h>
  39 #include <sys/mman.h>
  40 #include <string.h>
  41 #include <errno.h>
  42 #include <fcntl.h>
  43 #include <unistd.h>
  44 #include <ctype.h>
  45 #include <assert.h>
  46
  47 #include <talloc.h>
  48
  49 #include <gmime/gmime.h>
  50
  51 #include "xutil.h"
  52 #include "error_util.h"
  53 #include "string-util.h"
  54
  55 #ifdef DEBUG
  56 # define DEBUG_DATABASE_SANITY 1
  57 # define DEBUG_QUERY 1
  58 #endif
  59
  60 #define COMPILE_TIME_ASSERT(pred) ((void)sizeof(char[1 - 2*!(pred)]))
  61
  62 #define STRNCMP_LITERAL(var, literal) \
  63     strncmp ((var), (literal), sizeof (literal) - 1)
  64
  65 /* Robust bit test/set/reset macros */
  66 #define _NOTMUCH_VALID_BIT(bit) \
  67     ((bit) >= 0 && ((unsigned long) bit) < CHAR_BIT * sizeof (unsigned long long))
  68 #define NOTMUCH_TEST_BIT(val, bit) \
  69     (_NOTMUCH_VALID_BIT(bit) ? !!((val) & (1ull << (bit))) : 0)
  70 #define NOTMUCH_SET_BIT(valp, bit) \
  71     (_NOTMUCH_VALID_BIT(bit) ? (*(valp) |= (1ull << (bit))) : *(valp))
  72 #define NOTMUCH_CLEAR_BIT(valp,  bit) \
  73     (_NOTMUCH_VALID_BIT(bit) ? (*(valp) &= ~(1ull << (bit))) : *(valp))
  74
  75 #define unused(x) x __attribute__ ((unused))
  76
  77 /* Thanks to Andrew Tridgell's (SAMBA's) talloc for this definition of
  78  * unlikely. The talloc source code comes to us via the GNU LGPL v. 3.
  79  */
  80 /* these macros gain us a few percent of speed on gcc */
  81 #if (__GNUC__ >= 3)
  82 /* the strange !! is to ensure that __builtin_expect() takes either 0 or 1
  83    as its first argument */
  84 #ifndef likely
  85 #define likely(x)   __builtin_expect(!!(x), 1)
  86 #endif
  87 #ifndef unlikely
  88 #define unlikely(x) __builtin_expect(!!(x), 0)
  89 #endif
  90 #else
  91 #ifndef likely
  92 #define likely(x) (x)
  93 #endif
  94 #ifndef unlikely
  95 #define unlikely(x) (x)
  96 #endif
  97 #endif
  98
  99 typedef enum {
 100     NOTMUCH_VALUE_TIMESTAMP = 0,
 101     NOTMUCH_VALUE_MESSAGE_ID,
 102     NOTMUCH_VALUE_FROM,
 103     NOTMUCH_VALUE_SUBJECT,
 104     NOTMUCH_VALUE_LAST_MOD,
 105 } notmuch_value_t;
 106
 107 /* Xapian (with flint backend) complains if we provide a term longer
 108  * than this, but I haven't yet found a way to query the limit
 109  * programmatically. */
 110 #define NOTMUCH_TERM_MAX 245
 111
 112 #define NOTMUCH_METADATA_THREAD_ID_PREFIX "thread_id_"
 113
 114 /* For message IDs we have to be even more restrictive. Beyond fitting
 115  * into the term limit, we also use message IDs to construct
 116  * metadata-key values. And the documentation says that these should
 117  * be restricted to about 200 characters. (The actual limit for the
 118  * chert backend at least is 252.)
 119  */
 120 #define NOTMUCH_MESSAGE_ID_MAX (200 - sizeof (NOTMUCH_METADATA_THREAD_ID_PREFIX))
 121
 122 typedef enum _notmuch_private_status {
 123     /* First, copy all the public status values. */
 124     NOTMUCH_PRIVATE_STATUS_SUCCESS = NOTMUCH_STATUS_SUCCESS,
 125     NOTMUCH_PRIVATE_STATUS_OUT_OF_MEMORY = NOTMUCH_STATUS_OUT_OF_MEMORY,
 126     NOTMUCH_PRIVATE_STATUS_READ_ONLY_DATABASE = NOTMUCH_STATUS_READ_ONLY_DATABASE,
 127     NOTMUCH_PRIVATE_STATUS_XAPIAN_EXCEPTION = NOTMUCH_STATUS_XAPIAN_EXCEPTION,
 128     NOTMUCH_PRIVATE_STATUS_FILE_NOT_EMAIL = NOTMUCH_STATUS_FILE_NOT_EMAIL,
 129     NOTMUCH_PRIVATE_STATUS_NULL_POINTER = NOTMUCH_STATUS_NULL_POINTER,
 130     NOTMUCH_PRIVATE_STATUS_TAG_TOO_LONG = NOTMUCH_STATUS_TAG_TOO_LONG,
 131     NOTMUCH_PRIVATE_STATUS_UNBALANCED_FREEZE_THAW = NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW,
 132
 133     /* Then add our own private values. */
 134     NOTMUCH_PRIVATE_STATUS_TERM_TOO_LONG = NOTMUCH_STATUS_LAST_STATUS,
 135     NOTMUCH_PRIVATE_STATUS_NO_DOCUMENT_FOUND,
 136
 137     NOTMUCH_PRIVATE_STATUS_LAST_STATUS
 138 } notmuch_private_status_t;
 139
 140 /* Coerce a notmuch_private_status_t value to a notmuch_status_t
 141  * value, generating an internal error if the private value is equal
 142  * to or greater than NOTMUCH_STATUS_LAST_STATUS. (The idea here is
 143  * that the caller has previously handled any expected
 144  * notmuch_private_status_t values.)
 145  *
 146  * Note that the function _internal_error does not return. Evaluating
 147  * to NOTMUCH_STATUS_SUCCESS is done purely to appease the compiler.
 148  */
 149 #define COERCE_STATUS(private_status, format, ...)                      \
 150     ((private_status >= (notmuch_private_status_t) NOTMUCH_STATUS_LAST_STATUS)\
 151      ?                                                                  \
 152      _internal_error (format " (%s).\n",                                \
 153                       ##__VA_ARGS__,                                    \
 154                       __location__),                                    \
 155      (notmuch_status_t) NOTMUCH_PRIVATE_STATUS_SUCCESS                  \
 156      :                                                                  \
 157      (notmuch_status_t) private_status)
 158
 159 /* Flags shared by various lookup functions. */
 160 typedef enum _notmuch_find_flags {
 161     /* Lookup without creating any documents.  This is the default
 162      * behavior. */
 163     NOTMUCH_FIND_LOOKUP = 0,
 164     /* If set, create the necessary document (or documents) if they
 165      * are missing.  Requires a read/write database. */
 166     NOTMUCH_FIND_CREATE = 1<<0,
 167 } notmuch_find_flags_t;
 168
 169 typedef struct _notmuch_doc_id_set notmuch_doc_id_set_t;
 170
 171 /* database.cc */
 172
 173 /* Lookup a prefix value by name.
 174  *
 175  * XXX: This should really be static inside of message.cc, and we can
 176  * do that once we convert database.cc to use the
 177  * _notmuch_message_add/remove_term functions. */
 178 const char *
 179 _find_prefix (const char *name);
 180
 181 char *
 182 _notmuch_message_id_compressed (void *ctx, const char *message_id);
 183
 184 notmuch_status_t
 185 _notmuch_database_ensure_writable (notmuch_database_t *notmuch);
 186
 187 notmuch_status_t
 188 _notmuch_database_reopen (notmuch_database_t *notmuch);
 189
 190 void
 191 _notmuch_database_log (notmuch_database_t *notmuch,
 192                        const char *format, ...);
 193
 194 void
 195 _notmuch_database_log_append (notmuch_database_t *notmuch,
 196                               const char *format, ...);
 197
 198 unsigned long
 199 _notmuch_database_new_revision (notmuch_database_t *notmuch);
 200
 201 const char *
 202 _notmuch_database_relative_path (notmuch_database_t *notmuch,
 203                                  const char *path);
 204
 205 notmuch_status_t
 206 _notmuch_database_split_path (void *ctx,
 207                               const char *path,
 208                               const char **directory,
 209                               const char **basename);
 210
 211 const char *
 212 _notmuch_database_get_directory_db_path (const char *path);
 213
 214 unsigned int
 215 _notmuch_database_generate_doc_id (notmuch_database_t *notmuch);
 216
 217 notmuch_private_status_t
 218 _notmuch_database_find_unique_doc_id (notmuch_database_t *notmuch,
 219                                       const char *prefix_name,
 220                                       const char *value,
 221                                       unsigned int *doc_id);
 222
 223 notmuch_status_t
 224 _notmuch_database_find_directory_id (notmuch_database_t *database,
 225                                      const char *path,
 226                                      notmuch_find_flags_t flags,
 227                                      unsigned int *directory_id);
 228
 229 const char *
 230 _notmuch_database_get_directory_path (void *ctx,
 231                                       notmuch_database_t *notmuch,
 232                                       unsigned int doc_id);
 233
 234 notmuch_status_t
 235 _notmuch_database_filename_to_direntry (void *ctx,
 236                                         notmuch_database_t *notmuch,
 237                                         const char *filename,
 238                                         notmuch_find_flags_t flags,
 239                                         char **direntry);
 240
 241 /* directory.cc */
 242
 243 notmuch_directory_t *
 244 _notmuch_directory_create (notmuch_database_t *notmuch,
 245                            const char *path,
 246                            notmuch_find_flags_t flags,
 247                            notmuch_status_t *status_ret);
 248
 249 unsigned int
 250 _notmuch_directory_get_document_id (notmuch_directory_t *directory);
 251
 252 /* message.cc */
 253
 254 notmuch_message_t *
 255 _notmuch_message_create (const void *talloc_owner,
 256                          notmuch_database_t *notmuch,
 257                          unsigned int doc_id,
 258                          notmuch_private_status_t *status);
 259
 260 notmuch_message_t *
 261 _notmuch_message_create_for_message_id (notmuch_database_t *notmuch,
 262                                         const char *message_id,
 263                                         notmuch_private_status_t *status);
 264
 265 unsigned int
 266 _notmuch_message_get_doc_id (notmuch_message_t *message);
 267
 268 const char *
 269 _notmuch_message_get_in_reply_to (notmuch_message_t *message);
 270
 271 notmuch_private_status_t
 272 _notmuch_message_add_term (notmuch_message_t *message,
 273                            const char *prefix_name,
 274                            const char *value);
 275
 276 notmuch_private_status_t
 277 _notmuch_message_remove_term (notmuch_message_t *message,
 278                               const char *prefix_name,
 279                               const char *value);
 280
 281 notmuch_private_status_t
 282 _notmuch_message_has_term (notmuch_message_t *message,
 283                            const char *prefix_name,
 284                            const char *value,
 285                            notmuch_bool_t *result);
 286
 287 notmuch_private_status_t
 288 _notmuch_message_gen_terms (notmuch_message_t *message,
 289                             const char *prefix_name,
 290                             const char *text);
 291
 292 void
 293 _notmuch_message_upgrade_filename_storage (notmuch_message_t *message);
 294
 295 void
 296 _notmuch_message_upgrade_folder (notmuch_message_t *message);
 297
 298 notmuch_status_t
 299 _notmuch_message_add_filename (notmuch_message_t *message,
 300                                const char *filename);
 301
 302 notmuch_status_t
 303 _notmuch_message_remove_filename (notmuch_message_t *message,
 304                                   const char *filename);
 305
 306 notmuch_status_t
 307 _notmuch_message_rename (notmuch_message_t *message,
 308                          const char *new_filename);
 309
 310 void
 311 _notmuch_message_ensure_thread_id (notmuch_message_t *message);
 312
 313 void
 314 _notmuch_message_set_header_values (notmuch_message_t *message,
 315                                     const char *date,
 316                                     const char *from,
 317                                     const char *subject);
 318
 319 void
 320 _notmuch_message_upgrade_last_mod (notmuch_message_t *message);
 321
 322 void
 323 _notmuch_message_sync (notmuch_message_t *message);
 324
 325 notmuch_status_t
 326 _notmuch_message_delete (notmuch_message_t *message);
 327
 328 notmuch_private_status_t
 329 _notmuch_message_initialize_ghost (notmuch_message_t *message,
 330                                    const char *thread_id);
 331
 332 void
 333 _notmuch_message_close (notmuch_message_t *message);
 334
 335 /* Get a copy of the data in this message document.
 336  *
 337  * Caller should talloc_free the result when done.
 338  *
 339  * This function is intended to support database upgrade and really
 340  * shouldn't be used otherwise. */
 341 char *
 342 _notmuch_message_talloc_copy_data (notmuch_message_t *message);
 343
 344 /* Clear the data in this message document.
 345  *
 346  * This function is intended to support database upgrade and really
 347  * shouldn't be used otherwise. */
 348 void
 349 _notmuch_message_clear_data (notmuch_message_t *message);
 350
 351 /* Set the author member of 'message' - this is the representation used
 352  * when displaying the message */
 353 void
 354 _notmuch_message_set_author (notmuch_message_t *message, const char *author);
 355
 356 /* Get the author member of 'message' */
 357 const char *
 358 _notmuch_message_get_author (notmuch_message_t *message);
 359
 360 /* message-file.c */
 361
 362 /* XXX: I haven't decided yet whether these will actually get exported
 363  * into the public interface in notmuch.h
 364  */
 365
 366 typedef struct _notmuch_message_file notmuch_message_file_t;
 367
 368 /* Open a file containing a single email message.
 369  *
 370  * The caller should call notmuch_message_close when done with this.
 371  *
 372  * Returns NULL if any error occurs.
 373  */
 374 notmuch_message_file_t *
 375 _notmuch_message_file_open (notmuch_database_t *notmuch, const char *filename);
 376
 377 /* Like notmuch_message_file_open but with 'ctx' as the talloc owner. */
 378 notmuch_message_file_t *
 379 _notmuch_message_file_open_ctx (notmuch_database_t *notmuch,
 380                                 void *ctx, const char *filename);
 381
 382 /* Close a notmuch message previously opened with notmuch_message_open. */
 383 void
 384 _notmuch_message_file_close (notmuch_message_file_t *message);
 385
 386 /* Parse the message.
 387  *
 388  * This will be done automatically as necessary on other calls
 389  * depending on it, but an explicit call allows for better error
 390  * status reporting.
 391  */
 392 notmuch_status_t
 393 _notmuch_message_file_parse (notmuch_message_file_t *message);
 394
 395 /* Get the gmime message of a message file.
 396  *
 397  * The message file is parsed as necessary.
 398  *
 399  * The GMimeMessage* is set to *mime_message on success (which the
 400  * caller must not unref).
 401  *
 402  * XXX: Would be nice to not have to expose GMimeMessage here.
 403  */
 404 notmuch_status_t
 405 _notmuch_message_file_get_mime_message (notmuch_message_file_t *message,
 406                                         GMimeMessage **mime_message);
 407
 408 /* Get the value of the specified header from the message as a UTF-8 string.
 409  *
 410  * The message file is parsed as necessary.
 411  *
 412  * The header name is case insensitive.
 413  *
 414  * The Received: header is special - for it all Received: headers in
 415  * the message are concatenated
 416  *
 417  * The returned value is owned by the notmuch message and is valid
 418  * only until the message is closed. The caller should copy it if
 419  * needing to modify the value or to hold onto it for longer.
 420  *
 421  * Returns NULL on errors, empty string if the message does not
 422  * contain a header line matching 'header'.
 423  */
 424 const char *
 425 _notmuch_message_file_get_header (notmuch_message_file_t *message,
 426                                  const char *header);
 427
 428 /* index.cc */
 429
 430 notmuch_status_t
 431 _notmuch_message_index_file (notmuch_message_t *message,
 432                              notmuch_message_file_t *message_file);
 433
 434 /* messages.c */
 435
 436 typedef struct _notmuch_message_node {
 437     notmuch_message_t *message;
 438     struct _notmuch_message_node *next;
 439 } notmuch_message_node_t;
 440
 441 typedef struct _notmuch_message_list {
 442     notmuch_message_node_t *head;
 443     notmuch_message_node_t **tail;
 444 } notmuch_message_list_t;
 445
 446 /* There's a rumor that there's an alternate struct _notmuch_messages
 447  * somewhere with some nasty C++ objects in it. We'll try to maintain
 448  * ignorance of that here. (See notmuch_mset_messages_t in query.cc)
 449  */
 450 struct _notmuch_messages {
 451     notmuch_bool_t is_of_list_type;
 452     notmuch_doc_id_set_t *excluded_doc_ids;
 453     notmuch_message_node_t *iterator;
 454 };
 455
 456 notmuch_message_list_t *
 457 _notmuch_message_list_create (const void *ctx);
 458
 459 void
 460 _notmuch_message_list_add_message (notmuch_message_list_t *list,
 461                                    notmuch_message_t *message);
 462
 463 notmuch_messages_t *
 464 _notmuch_messages_create (notmuch_message_list_t *list);
 465
 466 /* query.cc */
 467
 468 notmuch_bool_t
 469 _notmuch_mset_messages_valid (notmuch_messages_t *messages);
 470
 471 notmuch_message_t *
 472 _notmuch_mset_messages_get (notmuch_messages_t *messages);
 473
 474 void
 475 _notmuch_mset_messages_move_to_next (notmuch_messages_t *messages);
 476
 477 notmuch_bool_t
 478 _notmuch_doc_id_set_contains (notmuch_doc_id_set_t *doc_ids,
 479                               unsigned int doc_id);
 480
 481 void
 482 _notmuch_doc_id_set_remove (notmuch_doc_id_set_t *doc_ids,
 483                             unsigned int doc_id);
 484
 485 /* querying xapian documents by type (e.g. "mail" or "ghost"): */
 486 notmuch_status_t
 487 _notmuch_query_search_documents (notmuch_query_t *query,
 488                                  const char *type,
 489                                  notmuch_messages_t **out);
 490
 491 notmuch_status_t
 492 _notmuch_query_count_documents (notmuch_query_t *query,
 493                                 const char *type,
 494                                 unsigned *count_out);
 495
 496 /* message.cc */
 497
 498 void
 499 _notmuch_message_add_reply (notmuch_message_t *message,
 500                             notmuch_message_t *reply);
 501 notmuch_database_t *
 502 _notmuch_message_database (notmuch_message_t *message);
 503
 504 /* sha1.c */
 505
 506 char *
 507 _notmuch_sha1_of_string (const char *str);
 508
 509 char *
 510 _notmuch_sha1_of_file (const char *filename);
 511
 512 /* string-list.c */
 513
 514 typedef struct _notmuch_string_node {
 515     char *string;
 516     struct _notmuch_string_node *next;
 517 } notmuch_string_node_t;
 518
 519 typedef struct _notmuch_string_list {
 520     int length;
 521     notmuch_string_node_t *head;
 522     notmuch_string_node_t **tail;
 523 } notmuch_string_list_t;
 524
 525 notmuch_string_list_t *
 526 _notmuch_string_list_create (const void *ctx);
 527
 528 /* Add 'string' to 'list'.
 529  *
 530  * The list will create its own talloced copy of 'string'.
 531  */
 532 void
 533 _notmuch_string_list_append (notmuch_string_list_t *list,
 534                              const char *string);
 535
 536 void
 537 _notmuch_string_list_sort (notmuch_string_list_t *list);
 538
 539 /* string-map.c */
 540 typedef struct _notmuch_string_map  notmuch_string_map_t;
 541 typedef struct _notmuch_string_map_iterator notmuch_string_map_iterator_t;
 542 notmuch_string_map_t *
 543 _notmuch_string_map_create (const void *ctx);
 544
 545 void
 546 _notmuch_string_map_append (notmuch_string_map_t *map,
 547                             const char *key,
 548                             const char *value);
 549
 550 const char *
 551 _notmuch_string_map_get (notmuch_string_map_t *map, const char *key);
 552
 553 notmuch_string_map_iterator_t *
 554 _notmuch_string_map_iterator_create (notmuch_string_map_t *map, const char *key,
 555                                      notmuch_bool_t exact);
 556
 557 notmuch_bool_t
 558 _notmuch_string_map_iterator_valid (notmuch_string_map_iterator_t *iter);
 559
 560 void
 561 _notmuch_string_map_iterator_move_to_next (notmuch_string_map_iterator_t *iter);
 562
 563 const char *
 564 _notmuch_string_map_iterator_key (notmuch_string_map_iterator_t *iterator);
 565
 566 const char *
 567 _notmuch_string_map_iterator_value (notmuch_string_map_iterator_t *iterator);
 568
 569 void
 570 _notmuch_string_map_iterator_destroy (notmuch_string_map_iterator_t *iterator);
 571
 572 /* tags.c */
 573
 574 notmuch_tags_t *
 575 _notmuch_tags_create (const void *ctx, notmuch_string_list_t *list);
 576
 577 /* filenames.c */
 578
 579 /* The notmuch_filenames_t iterates over a notmuch_string_list_t of
 580  * file names */
 581 notmuch_filenames_t *
 582 _notmuch_filenames_create (const void *ctx,
 583                            notmuch_string_list_t *list);
 584
 585 /* thread.cc */
 586
 587 notmuch_thread_t *
 588 _notmuch_thread_create (void *ctx,
 589                         notmuch_database_t *notmuch,
 590                         unsigned int seed_doc_id,
 591                         notmuch_doc_id_set_t *match_set,
 592                         notmuch_string_list_t *excluded_terms,
 593                         notmuch_exclude_t omit_exclude,
 594                         notmuch_sort_t sort);
 595
 596 NOTMUCH_END_DECLS
 597
 598 #ifdef __cplusplus
 599 /* Implicit typecast from 'void *' to 'T *' is okay in C, but not in
 600  * C++. In talloc_steal, an explicit cast is provided for type safety
 601  * in some GCC versions. Otherwise, a cast is required. Provide a
 602  * template function for this to maintain type safety, and redefine
 603  * talloc_steal to use it.
 604  */
 605 #if !(__GNUC__ >= 3)
 606 template <class T> T *
 607 _notmuch_talloc_steal (const void *new_ctx, const T *ptr)
 608 {
 609     return static_cast<T *> (talloc_steal (new_ctx, ptr));
 610 }
 611 #undef talloc_steal
 612 #define talloc_steal _notmuch_talloc_steal
 613 #endif
 614 #endif
 615
 616 #endif