1 Return-Path: <jani@nikula.org>
\r
2 X-Original-To: notmuch@notmuchmail.org
\r
3 Delivered-To: notmuch@notmuchmail.org
\r
4 Received: from localhost (localhost [127.0.0.1])
\r
5 by olra.theworths.org (Postfix) with ESMTP id D9773431E64
\r
6 for <notmuch@notmuchmail.org>; Sat, 30 Nov 2013 07:43:14 -0800 (PST)
\r
7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
\r
8 X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References"
\r
12 X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5
\r
13 tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled
\r
14 Received: from olra.theworths.org ([127.0.0.1])
\r
15 by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)
\r
16 with ESMTP id BiVfm2+OTZnG for <notmuch@notmuchmail.org>;
\r
17 Sat, 30 Nov 2013 07:43:06 -0800 (PST)
\r
18 Received: from mail-lb0-f172.google.com (mail-lb0-f172.google.com
\r
19 [209.85.217.172]) (using TLSv1 with cipher RC4-SHA (128/128 bits))
\r
20 (No client certificate requested)
\r
21 by olra.theworths.org (Postfix) with ESMTPS id EF8DB431FAF
\r
22 for <notmuch@notmuchmail.org>; Sat, 30 Nov 2013 07:43:05 -0800 (PST)
\r
23 Received: by mail-lb0-f172.google.com with SMTP id z5so7760865lbh.31
\r
24 for <notmuch@notmuchmail.org>; Sat, 30 Nov 2013 07:43:04 -0800 (PST)
\r
25 X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
\r
26 d=1e100.net; s=20130820;
\r
27 h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to
\r
28 :references:in-reply-to:references;
\r
29 bh=mIzr7K22IkGFmYoDJDhtKQxG+ky7nZ/irfRb5YFPbO8=;
\r
30 b=d3TLbP7Xc1u3nyftsrKl6QqQ8wxne2xGfCUMYbVGAnvN5h1lLK0QJjcx6GBBolFxkq
\r
31 JKQLwvZ9WVISdP4CTDy/q9AU9wVeyYm3iM8XhRnuOI+/7v2H67PPtUQEzvYmYBPmyCOr
\r
32 3c2htbJfQSPyv5QoU8CPZm23qOdGdliv4rasFQg1qzudsWbK40MHZsrLvxHfx/3hYwwt
\r
33 OO1exAwQrRCu/45kF2/WQAG9Gs0Xl+iSJ1ZzWNCe8uBA/xNYLzGUeG1AMoG/V7EKd8Zk
\r
34 8wBImyRfYLZVNWCAiAVuAgj2jFc5nLrctENPIXgUlyqrThyMWfKwBV9abUqrc/9G293x
\r
37 ALoCoQkDPV+UA6Bn16MeCLXwZVemt/JthxZDHI7VoiWxHR2ojD7V0k7g+frzvCJ0C1TaEpH5pnW9
\r
38 X-Received: by 10.152.22.4 with SMTP id z4mr39534839lae.14.1385826184527;
\r
39 Sat, 30 Nov 2013 07:43:04 -0800 (PST)
\r
40 Received: from localhost (dsl-hkibrasgw2-58c36f-91.dhcp.inet.fi.
\r
41 [88.195.111.91]) by mx.google.com with ESMTPSA id
\r
42 mq10sm55844339lbb.12.2013.11.30.07.43.01 for <multiple recipients>
\r
43 (version=TLSv1.2 cipher=RC4-SHA bits=128/128);
\r
44 Sat, 30 Nov 2013 07:43:03 -0800 (PST)
\r
45 From: Jani Nikula <jani@nikula.org>
\r
46 To: notmuch@notmuchmail.org
\r
47 Subject: [PATCH 2/2] lib: modify notmuch.h for automatic document generation
\r
48 Date: Sat, 30 Nov 2013 17:42:52 +0200
\r
50 <8900d3fb7b01b8b97f35deb8030affea32d50fe9.1385826040.git.jani@nikula.org>
\r
51 X-Mailer: git-send-email 1.8.4.2
\r
52 In-Reply-To: <cover.1385826040.git.jani@nikula.org>
\r
53 References: <cover.1385826040.git.jani@nikula.org>
\r
54 In-Reply-To: <cover.1385826040.git.jani@nikula.org>
\r
55 References: <cover.1385826040.git.jani@nikula.org>
\r
56 X-BeenThere: notmuch@notmuchmail.org
\r
57 X-Mailman-Version: 2.1.13
\r
59 List-Id: "Use and development of the notmuch mail system."
\r
60 <notmuch.notmuchmail.org>
\r
61 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
62 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
63 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
64 List-Post: <mailto:notmuch@notmuchmail.org>
\r
65 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
66 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
67 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
68 X-List-Received-Date: Sat, 30 Nov 2013 15:43:15 -0000
\r
70 Minimal changes to produce a sensible result.
\r
72 lib/notmuch.h | 436 +++++++++++++++++++++++++++++++++++++++-------------------
\r
73 1 file changed, 296 insertions(+), 140 deletions(-)
\r
75 diff --git a/lib/notmuch.h b/lib/notmuch.h
\r
76 index 7c3a30c..708b603 100644
\r
80 * Author: Carl Worth <cworth@cworth.org>
\r
84 + * @defgroup notmuch The notmuch API
\r
86 + * Not much of an email library, (just index and search)
\r
94 +#ifndef __DOXYGEN__
\r
97 # define NOTMUCH_BEGIN_DECLS extern "C" {
\r
98 # define NOTMUCH_END_DECLS }
\r
99 @@ -45,18 +55,20 @@ NOTMUCH_BEGIN_DECLS
\r
100 #define NOTMUCH_MINOR_VERSION 17
\r
101 #define NOTMUCH_MICRO_VERSION 0
\r
104 +#endif /* __DOXYGEN__ */
\r
107 * Check the version of the notmuch library being compiled against.
\r
109 * Return true if the library being compiled against is of the
\r
110 * specified version or above. For example:
\r
112 - * #if NOTMUCH_CHECK_VERSION(0, 18, 0)
\r
113 + * \#if NOTMUCH_CHECK_VERSION(0, 18, 0)
\r
114 * (code requiring notmuch 0.18 or above)
\r
118 * NOTMUCH_CHECK_VERSION has been defined since version 0.17.0; you
\r
119 - * can use #if !defined(NOTMUCH_CHECK_VERSION) to check for versions
\r
120 + * can use \#if !defined(NOTMUCH_CHECK_VERSION) to check for versions
\r
123 #define NOTMUCH_CHECK_VERSION (major, minor, micro) \
\r
124 @@ -65,80 +77,97 @@ NOTMUCH_BEGIN_DECLS
\r
125 (NOTMUCH_MAJOR_VERSION == (major) && NOTMUCH_MINOR_VERSION == (minor) && \
\r
126 NOTMUCH_MICRO_VERSION >= (micro)))
\r
129 + * Notmuch boolean type.
\r
131 typedef int notmuch_bool_t;
\r
133 -/* Status codes used for the return values of most functions.
\r
135 + * Status codes used for the return values of most functions.
\r
137 * A zero value (NOTMUCH_STATUS_SUCCESS) indicates that the function
\r
138 - * completed without error. Any other value indicates an error as
\r
141 - * NOTMUCH_STATUS_SUCCESS: No error occurred.
\r
143 - * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory
\r
145 - * XXX: We don't really want to expose this lame XAPIAN_EXCEPTION
\r
146 - * value. Instead we should map to things like DATABASE_LOCKED or
\r
149 - * NOTMUCH_STATUS_READ_ONLY_DATABASE: An attempt was made to write to
\r
150 - * a database opened in read-only mode.
\r
151 + * completed without error. Any other value indicates an error.
\r
153 - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
\r
155 - * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to read or
\r
156 - * write to a file (this could be file not found, permission
\r
159 - * NOTMUCH_STATUS_FILE_NOT_EMAIL: A file was presented that doesn't
\r
160 - * appear to be an email message.
\r
162 - * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: A file contains a message ID
\r
163 - * that is identical to a message already in the database.
\r
165 - * NOTMUCH_STATUS_NULL_POINTER: The user erroneously passed a NULL
\r
166 - * pointer to a notmuch function.
\r
168 - * NOTMUCH_STATUS_TAG_TOO_LONG: A tag value is too long (exceeds
\r
169 - * NOTMUCH_TAG_MAX)
\r
171 - * NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: The notmuch_message_thaw
\r
172 - * function has been called more times than notmuch_message_freeze.
\r
174 - * NOTMUCH_STATUS_UNBALANCED_ATOMIC: notmuch_database_end_atomic has
\r
175 - * been called more times than notmuch_database_begin_atomic.
\r
179 - * NOTMUCH_STATUS_LAST_STATUS: Not an actual status value. Just a way
\r
180 - * to find out how many valid status values there are.
\r
182 typedef enum _notmuch_status {
\r
184 + * No error occurred.
\r
186 NOTMUCH_STATUS_SUCCESS = 0,
\r
190 NOTMUCH_STATUS_OUT_OF_MEMORY,
\r
192 + * An attempt was made to write to a database opened in read-only
\r
195 NOTMUCH_STATUS_READ_ONLY_DATABASE,
\r
197 + * A Xapian exception occurred.
\r
199 NOTMUCH_STATUS_XAPIAN_EXCEPTION,
\r
201 + * An error occurred trying to read or write to a file (this could
\r
202 + * be file not found, permission denied, etc.)
\r
204 + * @todo We don't really want to expose this lame XAPIAN_EXCEPTION
\r
205 + * value. Instead we should map to things like DATABASE_LOCKED or
\r
208 NOTMUCH_STATUS_FILE_ERROR,
\r
210 + * A file was presented that doesn't appear to be an email
\r
213 NOTMUCH_STATUS_FILE_NOT_EMAIL,
\r
215 + * A file contains a message ID that is identical to a message
\r
216 + * already in the database.
\r
218 NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID,
\r
220 + * The user erroneously passed a NULL pointer to a notmuch
\r
223 NOTMUCH_STATUS_NULL_POINTER,
\r
225 + * A tag value is too long (exceeds NOTMUCH_TAG_MAX).
\r
227 NOTMUCH_STATUS_TAG_TOO_LONG,
\r
229 + * The notmuch_message_thaw function has been called more times
\r
230 + * than notmuch_message_freeze.
\r
232 NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW,
\r
234 + * notmuch_database_end_atomic has been called more times than
\r
235 + * notmuch_database_begin_atomic.
\r
237 NOTMUCH_STATUS_UNBALANCED_ATOMIC,
\r
239 + * The operation is not supported.
\r
241 NOTMUCH_STATUS_UNSUPPORTED_OPERATION,
\r
244 + * Not an actual status value. Just a way to find out how many
\r
245 + * valid status values there are.
\r
247 NOTMUCH_STATUS_LAST_STATUS
\r
248 } notmuch_status_t;
\r
250 -/* Get a string representation of a notmuch_status_t value.
\r
252 + * Get a string representation of a notmuch_status_t value.
\r
254 * The result is read-only.
\r
257 notmuch_status_to_string (notmuch_status_t status);
\r
260 /* Various opaque data types. For each notmuch_<foo>_t see the various
\r
261 * notmuch_<foo> functions below. */
\r
262 +#ifndef __DOXYGEN__
\r
263 typedef struct _notmuch_database notmuch_database_t;
\r
264 typedef struct _notmuch_query notmuch_query_t;
\r
265 typedef struct _notmuch_threads notmuch_threads_t;
\r
266 @@ -148,8 +177,10 @@ typedef struct _notmuch_message notmuch_message_t;
\r
267 typedef struct _notmuch_tags notmuch_tags_t;
\r
268 typedef struct _notmuch_directory notmuch_directory_t;
\r
269 typedef struct _notmuch_filenames notmuch_filenames_t;
\r
270 +#endif /* __DOXYGEN__ */
\r
272 -/* Create a new, empty notmuch database located at 'path'.
\r
274 + * Create a new, empty notmuch database located at 'path'.
\r
276 * The path should be a top-level directory to a collection of
\r
277 * plain-text email messages (one message per file). This call will
\r
278 @@ -185,12 +216,22 @@ typedef struct _notmuch_filenames notmuch_filenames_t;
\r
280 notmuch_database_create (const char *path, notmuch_database_t **database);
\r
283 + * Database open mode for notmuch_database_open.
\r
287 + * Open database for reading only.
\r
289 NOTMUCH_DATABASE_MODE_READ_ONLY = 0,
\r
291 + * Open database for reading and writing.
\r
293 NOTMUCH_DATABASE_MODE_READ_WRITE
\r
294 } notmuch_database_mode_t;
\r
296 -/* Open an existing notmuch database located at 'path'.
\r
298 + * Open an existing notmuch database located at 'path'.
\r
300 * The database should have been created at some time in the past,
\r
301 * (not necessarily by this process), by calling
\r
302 @@ -226,7 +267,8 @@ notmuch_database_open (const char *path,
\r
303 notmuch_database_mode_t mode,
\r
304 notmuch_database_t **database);
\r
306 -/* Close the given notmuch database.
\r
308 + * Close the given notmuch database.
\r
310 * After notmuch_database_close has been called, calls to other
\r
311 * functions on objects derived from this database may either behave
\r
312 @@ -240,12 +282,14 @@ notmuch_database_open (const char *path,
\r
314 notmuch_database_close (notmuch_database_t *database);
\r
316 -/* A callback invoked by notmuch_database_compact to notify the user
\r
318 + * A callback invoked by notmuch_database_compact to notify the user
\r
319 * of the progress of the compaction process.
\r
321 typedef void (*notmuch_compact_status_cb_t)(const char *message, void *closure);
\r
323 -/* Compact a notmuch database, backing up the original database to the
\r
325 + * Compact a notmuch database, backing up the original database to the
\r
328 * The database will be opened with NOTMUCH_DATABASE_MODE_READ_WRITE
\r
329 @@ -261,33 +305,41 @@ notmuch_database_compact (const char* path,
\r
330 notmuch_compact_status_cb_t status_cb,
\r
333 -/* Destroy the notmuch database, closing it if necessary and freeing
\r
335 + * Destroy the notmuch database, closing it if necessary and freeing
\r
336 * all associated resources.
\r
339 notmuch_database_destroy (notmuch_database_t *database);
\r
341 -/* Return the database path of the given database.
\r
343 + * Return the database path of the given database.
\r
345 * The return value is a string owned by notmuch so should not be
\r
346 - * modified nor freed by the caller. */
\r
347 + * modified nor freed by the caller.
\r
350 notmuch_database_get_path (notmuch_database_t *database);
\r
352 -/* Return the database format version of the given database. */
\r
354 + * Return the database format version of the given database.
\r
357 notmuch_database_get_version (notmuch_database_t *database);
\r
359 -/* Does this database need to be upgraded before writing to it?
\r
361 + * Does this database need to be upgraded before writing to it?
\r
363 * If this function returns TRUE then no functions that modify the
\r
364 * database (notmuch_database_add_message, notmuch_message_add_tag,
\r
365 * notmuch_directory_set_mtime, etc.) will work unless the function
\r
366 - * notmuch_database_upgrade is called successfully first. */
\r
367 + * notmuch_database_upgrade is called successfully first.
\r
370 notmuch_database_needs_upgrade (notmuch_database_t *database);
\r
372 -/* Upgrade the current database.
\r
374 + * Upgrade the current database.
\r
376 * After opening a database in read-write mode, the client should
\r
377 * check if an upgrade is needed (notmuch_database_needs_upgrade) and
\r
378 @@ -306,7 +358,8 @@ notmuch_database_upgrade (notmuch_database_t *database,
\r
382 -/* Begin an atomic database operation.
\r
384 + * Begin an atomic database operation.
\r
386 * Any modifications performed between a successful begin and a
\r
387 * notmuch_database_end_atomic will be applied to the database
\r
388 @@ -327,7 +380,8 @@ notmuch_database_upgrade (notmuch_database_t *database,
\r
390 notmuch_database_begin_atomic (notmuch_database_t *notmuch);
\r
392 -/* Indicate the end of an atomic database operation.
\r
394 + * Indicate the end of an atomic database operation.
\r
398 @@ -342,7 +396,8 @@ notmuch_database_begin_atomic (notmuch_database_t *notmuch);
\r
400 notmuch_database_end_atomic (notmuch_database_t *notmuch);
\r
402 -/* Retrieve a directory object from the database for 'path'.
\r
404 + * Retrieve a directory object from the database for 'path'.
\r
406 * Here, 'path' should be a path relative to the path of 'database'
\r
407 * (see notmuch_database_get_path), or else should be an absolute path
\r
408 @@ -365,7 +420,8 @@ notmuch_database_get_directory (notmuch_database_t *database,
\r
410 notmuch_directory_t **directory);
\r
412 -/* Add a new message to the given notmuch database or associate an
\r
414 + * Add a new message to the given notmuch database or associate an
\r
415 * additional filename with an existing message.
\r
417 * Here, 'filename' should be a path relative to the path of
\r
418 @@ -416,7 +472,8 @@ notmuch_database_add_message (notmuch_database_t *database,
\r
419 const char *filename,
\r
420 notmuch_message_t **message);
\r
422 -/* Remove a message filename from the given notmuch database. If the
\r
424 + * Remove a message filename from the given notmuch database. If the
\r
425 * message has no more filenames, remove the message.
\r
427 * If the same message (as determined by the message ID) is still
\r
428 @@ -444,7 +501,8 @@ notmuch_status_t
\r
429 notmuch_database_remove_message (notmuch_database_t *database,
\r
430 const char *filename);
\r
432 -/* Find a message with the given message_id.
\r
434 + * Find a message with the given message_id.
\r
436 * If a message with the given message_id is found then, on successful return
\r
437 * (NOTMUCH_STATUS_SUCCESS) '*message' will be initialized to a message
\r
438 @@ -471,7 +529,8 @@ notmuch_database_find_message (notmuch_database_t *database,
\r
439 const char *message_id,
\r
440 notmuch_message_t **message);
\r
442 -/* Find a message with the given filename.
\r
444 + * Find a message with the given filename.
\r
446 * If the database contains a message with the given filename then, on
\r
447 * successful return (NOTMUCH_STATUS_SUCCESS) '*message' will be initialized to
\r
448 @@ -498,7 +557,8 @@ notmuch_database_find_message_by_filename (notmuch_database_t *notmuch,
\r
449 const char *filename,
\r
450 notmuch_message_t **message);
\r
452 -/* Return a list of all tags found in the database.
\r
454 + * Return a list of all tags found in the database.
\r
456 * This function creates a list of all tags found in the database. The
\r
457 * resulting list contains all tags from all messages found in the database.
\r
458 @@ -508,7 +568,8 @@ notmuch_database_find_message_by_filename (notmuch_database_t *notmuch,
\r
460 notmuch_database_get_all_tags (notmuch_database_t *db);
\r
462 -/* Create a new query for 'database'.
\r
464 + * Create a new query for 'database'.
\r
466 * Here, 'database' should be an open database, (see
\r
467 * notmuch_database_open and notmuch_database_create).
\r
468 @@ -536,19 +597,36 @@ notmuch_query_t *
\r
469 notmuch_query_create (notmuch_database_t *database,
\r
470 const char *query_string);
\r
472 -/* Sort values for notmuch_query_set_sort */
\r
474 + * Sort values for notmuch_query_set_sort.
\r
480 NOTMUCH_SORT_OLDEST_FIRST,
\r
484 NOTMUCH_SORT_NEWEST_FIRST,
\r
486 + * Sort by message-id.
\r
488 NOTMUCH_SORT_MESSAGE_ID,
\r
492 NOTMUCH_SORT_UNSORTED
\r
495 -/* Return the query_string of this query. See notmuch_query_create. */
\r
497 + * Return the query_string of this query. See notmuch_query_create.
\r
500 notmuch_query_get_query_string (notmuch_query_t *query);
\r
502 -/* Exclude values for notmuch_query_set_omit_excluded. The strange
\r
504 + * Exclude values for notmuch_query_set_omit_excluded. The strange
\r
505 * order is to maintain backward compatibility: the old FALSE/TRUE
\r
506 * options correspond to the new
\r
507 * NOTMUCH_EXCLUDE_FLAG/NOTMUCH_EXCLUDE_TRUE options.
\r
508 @@ -560,7 +638,8 @@ typedef enum {
\r
509 NOTMUCH_EXCLUDE_ALL
\r
510 } notmuch_exclude_t;
\r
512 -/* Specify whether to omit excluded results or simply flag them. By
\r
514 + * Specify whether to omit excluded results or simply flag them. By
\r
515 * default, this is set to TRUE.
\r
517 * If set to TRUE or ALL, notmuch_query_search_messages will omit excluded
\r
518 @@ -590,21 +669,29 @@ void
\r
519 notmuch_query_set_omit_excluded (notmuch_query_t *query,
\r
520 notmuch_exclude_t omit_excluded);
\r
522 -/* Specify the sorting desired for this query. */
\r
524 + * Specify the sorting desired for this query.
\r
527 notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
\r
529 -/* Return the sort specified for this query. See notmuch_query_set_sort. */
\r
531 + * Return the sort specified for this query. See
\r
532 + * notmuch_query_set_sort.
\r
535 notmuch_query_get_sort (notmuch_query_t *query);
\r
537 -/* Add a tag that will be excluded from the query results by default.
\r
539 + * Add a tag that will be excluded from the query results by default.
\r
540 * This exclusion will be overridden if this tag appears explicitly in
\r
545 notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag);
\r
547 -/* Execute a query for threads, returning a notmuch_threads_t object
\r
549 + * Execute a query for threads, returning a notmuch_threads_t object
\r
550 * which can be used to iterate over the results. The returned threads
\r
551 * object is owned by the query and as such, will only be valid until
\r
552 * notmuch_query_destroy.
\r
553 @@ -645,7 +732,8 @@ notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag);
\r
554 notmuch_threads_t *
\r
555 notmuch_query_search_threads (notmuch_query_t *query);
\r
557 -/* Execute a query for messages, returning a notmuch_messages_t object
\r
559 + * Execute a query for messages, returning a notmuch_messages_t object
\r
560 * which can be used to iterate over the results. The returned
\r
561 * messages object is owned by the query and as such, will only be
\r
562 * valid until notmuch_query_destroy.
\r
563 @@ -686,7 +774,8 @@ notmuch_query_search_threads (notmuch_query_t *query);
\r
564 notmuch_messages_t *
\r
565 notmuch_query_search_messages (notmuch_query_t *query);
\r
567 -/* Destroy a notmuch_query_t along with any associated resources.
\r
569 + * Destroy a notmuch_query_t along with any associated resources.
\r
571 * This will in turn destroy any notmuch_threads_t and
\r
572 * notmuch_messages_t objects generated by this query, (and in
\r
573 @@ -697,7 +786,8 @@ notmuch_query_search_messages (notmuch_query_t *query);
\r
575 notmuch_query_destroy (notmuch_query_t *query);
\r
577 -/* Is the given 'threads' iterator pointing at a valid thread.
\r
579 + * Is the given 'threads' iterator pointing at a valid thread.
\r
581 * When this function returns TRUE, notmuch_threads_get will return a
\r
582 * valid object. Whereas when this function returns FALSE,
\r
583 @@ -709,7 +799,8 @@ notmuch_query_destroy (notmuch_query_t *query);
\r
585 notmuch_threads_valid (notmuch_threads_t *threads);
\r
587 -/* Get the current thread from 'threads' as a notmuch_thread_t.
\r
589 + * Get the current thread from 'threads' as a notmuch_thread_t.
\r
591 * Note: The returned thread belongs to 'threads' and has a lifetime
\r
592 * identical to it (and the query to which it belongs).
\r
593 @@ -723,7 +814,8 @@ notmuch_threads_valid (notmuch_threads_t *threads);
\r
595 notmuch_threads_get (notmuch_threads_t *threads);
\r
597 -/* Move the 'threads' iterator to the next thread.
\r
599 + * Move the 'threads' iterator to the next thread.
\r
601 * If 'threads' is already pointing at the last thread then the
\r
602 * iterator will be moved to a point just beyond that last thread,
\r
603 @@ -736,7 +828,8 @@ notmuch_threads_get (notmuch_threads_t *threads);
\r
605 notmuch_threads_move_to_next (notmuch_threads_t *threads);
\r
607 -/* Destroy a notmuch_threads_t object.
\r
609 + * Destroy a notmuch_threads_t object.
\r
611 * It's not strictly necessary to call this function. All memory from
\r
612 * the notmuch_threads_t object will be reclaimed when the
\r
613 @@ -745,7 +838,8 @@ notmuch_threads_move_to_next (notmuch_threads_t *threads);
\r
615 notmuch_threads_destroy (notmuch_threads_t *threads);
\r
617 -/* Return an estimate of the number of messages matching a search
\r
619 + * Return an estimate of the number of messages matching a search.
\r
621 * This function performs a search and returns Xapian's best
\r
622 * guess as to number of matching messages.
\r
623 @@ -755,8 +849,9 @@ notmuch_threads_destroy (notmuch_threads_t *threads);
\r
626 notmuch_query_count_messages (notmuch_query_t *query);
\r
628 -/* Return the number of threads matching a search.
\r
631 + * Return the number of threads matching a search.
\r
633 * This function performs a search and returns the number of unique thread IDs
\r
634 * in the matching messages. This is the same as number of threads matching a
\r
635 @@ -770,7 +865,8 @@ notmuch_query_count_messages (notmuch_query_t *query);
\r
637 notmuch_query_count_threads (notmuch_query_t *query);
\r
639 -/* Get the thread ID of 'thread'.
\r
641 + * Get the thread ID of 'thread'.
\r
643 * The returned string belongs to 'thread' and as such, should not be
\r
644 * modified by the caller and will only be valid for as long as the
\r
645 @@ -780,7 +876,8 @@ notmuch_query_count_threads (notmuch_query_t *query);
\r
647 notmuch_thread_get_thread_id (notmuch_thread_t *thread);
\r
649 -/* Get the total number of messages in 'thread'.
\r
651 + * Get the total number of messages in 'thread'.
\r
653 * This count consists of all messages in the database belonging to
\r
654 * this thread. Contrast with notmuch_thread_get_matched_messages() .
\r
655 @@ -788,7 +885,8 @@ notmuch_thread_get_thread_id (notmuch_thread_t *thread);
\r
657 notmuch_thread_get_total_messages (notmuch_thread_t *thread);
\r
659 -/* Get a notmuch_messages_t iterator for the top-level messages in
\r
661 + * Get a notmuch_messages_t iterator for the top-level messages in
\r
662 * 'thread' in oldest-first order.
\r
664 * This iterator will not necessarily iterate over all of the messages
\r
665 @@ -800,7 +898,8 @@ notmuch_thread_get_total_messages (notmuch_thread_t *thread);
\r
666 notmuch_messages_t *
\r
667 notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread);
\r
669 -/* Get a notmuch_thread_t iterator for all messages in 'thread' in
\r
671 + * Get a notmuch_thread_t iterator for all messages in 'thread' in
\r
672 * oldest-first order.
\r
674 * The returned list will be destroyed when the thread is destroyed.
\r
675 @@ -808,7 +907,8 @@ notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread);
\r
676 notmuch_messages_t *
\r
677 notmuch_thread_get_messages (notmuch_thread_t *thread);
\r
679 -/* Get the number of messages in 'thread' that matched the search.
\r
681 + * Get the number of messages in 'thread' that matched the search.
\r
683 * This count includes only the messages in this thread that were
\r
684 * matched by the search from which the thread was created and were
\r
685 @@ -819,7 +919,8 @@ notmuch_thread_get_messages (notmuch_thread_t *thread);
\r
687 notmuch_thread_get_matched_messages (notmuch_thread_t *thread);
\r
689 -/* Get the authors of 'thread' as a UTF-8 string.
\r
691 + * Get the authors of 'thread' as a UTF-8 string.
\r
693 * The returned string is a comma-separated list of the names of the
\r
694 * authors of mail messages in the query results that belong to this
\r
695 @@ -833,7 +934,8 @@ notmuch_thread_get_matched_messages (notmuch_thread_t *thread);
\r
697 notmuch_thread_get_authors (notmuch_thread_t *thread);
\r
699 -/* Get the subject of 'thread' as a UTF-8 string.
\r
701 + * Get the subject of 'thread' as a UTF-8 string.
\r
703 * The subject is taken from the first message (according to the query
\r
704 * order---see notmuch_query_set_sort) in the query results that
\r
705 @@ -847,17 +949,20 @@ notmuch_thread_get_authors (notmuch_thread_t *thread);
\r
707 notmuch_thread_get_subject (notmuch_thread_t *thread);
\r
709 -/* Get the date of the oldest message in 'thread' as a time_t value.
\r
711 + * Get the date of the oldest message in 'thread' as a time_t value.
\r
714 notmuch_thread_get_oldest_date (notmuch_thread_t *thread);
\r
716 -/* Get the date of the newest message in 'thread' as a time_t value.
\r
718 + * Get the date of the newest message in 'thread' as a time_t value.
\r
721 notmuch_thread_get_newest_date (notmuch_thread_t *thread);
\r
723 -/* Get the tags for 'thread', returning a notmuch_tags_t object which
\r
725 + * Get the tags for 'thread', returning a notmuch_tags_t object which
\r
726 * can be used to iterate over all tags.
\r
728 * Note: In the Notmuch database, tags are stored on individual
\r
729 @@ -896,11 +1001,14 @@ notmuch_thread_get_newest_date (notmuch_thread_t *thread);
\r
731 notmuch_thread_get_tags (notmuch_thread_t *thread);
\r
733 -/* Destroy a notmuch_thread_t object. */
\r
735 + * Destroy a notmuch_thread_t object.
\r
738 notmuch_thread_destroy (notmuch_thread_t *thread);
\r
740 -/* Is the given 'messages' iterator pointing at a valid message.
\r
742 + * Is the given 'messages' iterator pointing at a valid message.
\r
744 * When this function returns TRUE, notmuch_messages_get will return a
\r
745 * valid object. Whereas when this function returns FALSE,
\r
746 @@ -912,7 +1020,8 @@ notmuch_thread_destroy (notmuch_thread_t *thread);
\r
748 notmuch_messages_valid (notmuch_messages_t *messages);
\r
750 -/* Get the current message from 'messages' as a notmuch_message_t.
\r
752 + * Get the current message from 'messages' as a notmuch_message_t.
\r
754 * Note: The returned message belongs to 'messages' and has a lifetime
\r
755 * identical to it (and the query to which it belongs).
\r
756 @@ -926,7 +1035,8 @@ notmuch_messages_valid (notmuch_messages_t *messages);
\r
757 notmuch_message_t *
\r
758 notmuch_messages_get (notmuch_messages_t *messages);
\r
760 -/* Move the 'messages' iterator to the next message.
\r
762 + * Move the 'messages' iterator to the next message.
\r
764 * If 'messages' is already pointing at the last message then the
\r
765 * iterator will be moved to a point just beyond that last message,
\r
766 @@ -939,7 +1049,8 @@ notmuch_messages_get (notmuch_messages_t *messages);
\r
768 notmuch_messages_move_to_next (notmuch_messages_t *messages);
\r
770 -/* Destroy a notmuch_messages_t object.
\r
772 + * Destroy a notmuch_messages_t object.
\r
774 * It's not strictly necessary to call this function. All memory from
\r
775 * the notmuch_messages_t object will be reclaimed when the containing
\r
776 @@ -948,7 +1059,8 @@ notmuch_messages_move_to_next (notmuch_messages_t *messages);
\r
778 notmuch_messages_destroy (notmuch_messages_t *messages);
\r
780 -/* Return a list of tags from all messages.
\r
782 + * Return a list of tags from all messages.
\r
784 * The resulting list is guaranteed not to contain duplicated tags.
\r
786 @@ -963,7 +1075,8 @@ notmuch_messages_destroy (notmuch_messages_t *messages);
\r
788 notmuch_messages_collect_tags (notmuch_messages_t *messages);
\r
790 -/* Get the message ID of 'message'.
\r
792 + * Get the message ID of 'message'.
\r
794 * The returned string belongs to 'message' and as such, should not be
\r
795 * modified by the caller and will only be valid for as long as the
\r
796 @@ -977,7 +1090,8 @@ notmuch_messages_collect_tags (notmuch_messages_t *messages);
\r
798 notmuch_message_get_message_id (notmuch_message_t *message);
\r
800 -/* Get the thread ID of 'message'.
\r
802 + * Get the thread ID of 'message'.
\r
804 * The returned string belongs to 'message' and as such, should not be
\r
805 * modified by the caller and will only be valid for as long as the
\r
806 @@ -991,7 +1105,8 @@ notmuch_message_get_message_id (notmuch_message_t *message);
\r
808 notmuch_message_get_thread_id (notmuch_message_t *message);
\r
810 -/* Get a notmuch_messages_t iterator for all of the replies to
\r
812 + * Get a notmuch_messages_t iterator for all of the replies to
\r
815 * Note: This call only makes sense if 'message' was ultimately
\r
816 @@ -1011,7 +1126,8 @@ notmuch_message_get_thread_id (notmuch_message_t *message);
\r
817 notmuch_messages_t *
\r
818 notmuch_message_get_replies (notmuch_message_t *message);
\r
820 -/* Get a filename for the email corresponding to 'message'.
\r
822 + * Get a filename for the email corresponding to 'message'.
\r
824 * The returned filename is an absolute filename, (the initial
\r
825 * component will match notmuch_database_get_path() ).
\r
826 @@ -1029,7 +1145,8 @@ notmuch_message_get_replies (notmuch_message_t *message);
\r
828 notmuch_message_get_filename (notmuch_message_t *message);
\r
830 -/* Get all filenames for the email corresponding to 'message'.
\r
832 + * Get all filenames for the email corresponding to 'message'.
\r
834 * Returns a notmuch_filenames_t iterator listing all the filenames
\r
835 * associated with 'message'. These files may not have identical
\r
836 @@ -1041,31 +1158,40 @@ notmuch_message_get_filename (notmuch_message_t *message);
\r
837 notmuch_filenames_t *
\r
838 notmuch_message_get_filenames (notmuch_message_t *message);
\r
840 -/* Message flags */
\r
844 typedef enum _notmuch_message_flag {
\r
845 NOTMUCH_MESSAGE_FLAG_MATCH,
\r
846 NOTMUCH_MESSAGE_FLAG_EXCLUDED
\r
847 } notmuch_message_flag_t;
\r
849 -/* Get a value of a flag for the email corresponding to 'message'. */
\r
851 + * Get a value of a flag for the email corresponding to 'message'.
\r
854 notmuch_message_get_flag (notmuch_message_t *message,
\r
855 notmuch_message_flag_t flag);
\r
857 -/* Set a value of a flag for the email corresponding to 'message'. */
\r
859 + * Set a value of a flag for the email corresponding to 'message'.
\r
862 notmuch_message_set_flag (notmuch_message_t *message,
\r
863 notmuch_message_flag_t flag, notmuch_bool_t value);
\r
865 -/* Get the date of 'message' as a time_t value.
\r
867 + * Get the date of 'message' as a time_t value.
\r
869 * For the original textual representation of the Date header from the
\r
870 * message call notmuch_message_get_header() with a header value of
\r
875 notmuch_message_get_date (notmuch_message_t *message);
\r
877 -/* Get the value of the specified header from 'message' as a UTF-8 string.
\r
879 + * Get the value of the specified header from 'message' as a UTF-8 string.
\r
881 * Common headers are stored in the database when the message is
\r
882 * indexed and will be returned from the database. Other headers will
\r
883 @@ -1083,7 +1209,8 @@ notmuch_message_get_date (notmuch_message_t *message);
\r
885 notmuch_message_get_header (notmuch_message_t *message, const char *header);
\r
887 -/* Get the tags for 'message', returning a notmuch_tags_t object which
\r
889 + * Get the tags for 'message', returning a notmuch_tags_t object which
\r
890 * can be used to iterate over all tags.
\r
892 * The tags object is owned by the message and as such, will only be
\r
893 @@ -1116,10 +1243,13 @@ notmuch_message_get_header (notmuch_message_t *message, const char *header);
\r
895 notmuch_message_get_tags (notmuch_message_t *message);
\r
897 -/* The longest possible tag value. */
\r
899 + * The longest possible tag value.
\r
901 #define NOTMUCH_TAG_MAX 200
\r
903 -/* Add a tag to the given message.
\r
905 + * Add a tag to the given message.
\r
909 @@ -1136,7 +1266,8 @@ notmuch_message_get_tags (notmuch_message_t *message);
\r
911 notmuch_message_add_tag (notmuch_message_t *message, const char *tag);
\r
913 -/* Remove a tag from the given message.
\r
915 + * Remove a tag from the given message.
\r
919 @@ -1153,7 +1284,8 @@ notmuch_message_add_tag (notmuch_message_t *message, const char *tag);
\r
921 notmuch_message_remove_tag (notmuch_message_t *message, const char *tag);
\r
923 -/* Remove all tags from the given message.
\r
925 + * Remove all tags from the given message.
\r
927 * See notmuch_message_freeze for an example showing how to safely
\r
928 * replace tag values.
\r
929 @@ -1164,7 +1296,8 @@ notmuch_message_remove_tag (notmuch_message_t *message, const char *tag);
\r
931 notmuch_message_remove_all_tags (notmuch_message_t *message);
\r
933 -/* Add/remove tags according to maildir flags in the message filename(s)
\r
935 + * Add/remove tags according to maildir flags in the message filename(s).
\r
937 * This function examines the filenames of 'message' for maildir
\r
938 * flags, and adds or removes tags on 'message' as follows when these
\r
939 @@ -1198,7 +1331,8 @@ notmuch_message_remove_all_tags (notmuch_message_t *message);
\r
941 notmuch_message_maildir_flags_to_tags (notmuch_message_t *message);
\r
943 -/* Rename message filename(s) to encode tags as maildir flags
\r
945 + * Rename message filename(s) to encode tags as maildir flags.
\r
947 * Specifically, for each filename corresponding to this message:
\r
949 @@ -1234,7 +1368,8 @@ notmuch_message_maildir_flags_to_tags (notmuch_message_t *message);
\r
951 notmuch_message_tags_to_maildir_flags (notmuch_message_t *message);
\r
953 -/* Freeze the current state of 'message' within the database.
\r
955 + * Freeze the current state of 'message' within the database.
\r
957 * This means that changes to the message state, (via
\r
958 * notmuch_message_add_tag, notmuch_message_remove_tag, and
\r
959 @@ -1277,7 +1412,8 @@ notmuch_message_tags_to_maildir_flags (notmuch_message_t *message);
\r
961 notmuch_message_freeze (notmuch_message_t *message);
\r
963 -/* Thaw the current 'message', synchronizing any changes that may have
\r
965 + * Thaw the current 'message', synchronizing any changes that may have
\r
966 * occurred while 'message' was frozen into the notmuch database.
\r
968 * See notmuch_message_freeze for an example of how to use this
\r
969 @@ -1300,7 +1436,8 @@ notmuch_message_freeze (notmuch_message_t *message);
\r
971 notmuch_message_thaw (notmuch_message_t *message);
\r
973 -/* Destroy a notmuch_message_t object.
\r
975 + * Destroy a notmuch_message_t object.
\r
977 * It can be useful to call this function in the case of a single
\r
978 * query object with many messages in the result, (such as iterating
\r
979 @@ -1311,7 +1448,8 @@ notmuch_message_thaw (notmuch_message_t *message);
\r
981 notmuch_message_destroy (notmuch_message_t *message);
\r
983 -/* Is the given 'tags' iterator pointing at a valid tag.
\r
985 + * Is the given 'tags' iterator pointing at a valid tag.
\r
987 * When this function returns TRUE, notmuch_tags_get will return a
\r
988 * valid string. Whereas when this function returns FALSE,
\r
989 @@ -1323,7 +1461,8 @@ notmuch_message_destroy (notmuch_message_t *message);
\r
991 notmuch_tags_valid (notmuch_tags_t *tags);
\r
993 -/* Get the current tag from 'tags' as a string.
\r
995 + * Get the current tag from 'tags' as a string.
\r
997 * Note: The returned string belongs to 'tags' and has a lifetime
\r
998 * identical to it (and the query to which it ultimately belongs).
\r
999 @@ -1334,7 +1473,8 @@ notmuch_tags_valid (notmuch_tags_t *tags);
\r
1001 notmuch_tags_get (notmuch_tags_t *tags);
\r
1003 -/* Move the 'tags' iterator to the next tag.
\r
1005 + * Move the 'tags' iterator to the next tag.
\r
1007 * If 'tags' is already pointing at the last tag then the iterator
\r
1008 * will be moved to a point just beyond that last tag, (where
\r
1009 @@ -1347,7 +1487,8 @@ notmuch_tags_get (notmuch_tags_t *tags);
\r
1011 notmuch_tags_move_to_next (notmuch_tags_t *tags);
\r
1013 -/* Destroy a notmuch_tags_t object.
\r
1015 + * Destroy a notmuch_tags_t object.
\r
1017 * It's not strictly necessary to call this function. All memory from
\r
1018 * the notmuch_tags_t object will be reclaimed when the containing
\r
1019 @@ -1356,7 +1497,8 @@ notmuch_tags_move_to_next (notmuch_tags_t *tags);
\r
1021 notmuch_tags_destroy (notmuch_tags_t *tags);
\r
1023 -/* Store an mtime within the database for 'directory'.
\r
1025 + * Store an mtime within the database for 'directory'.
\r
1027 * The 'directory' should be an object retrieved from the database
\r
1028 * with notmuch_database_get_directory for a particular path.
\r
1029 @@ -1396,35 +1538,44 @@ notmuch_status_t
\r
1030 notmuch_directory_set_mtime (notmuch_directory_t *directory,
\r
1033 -/* Get the mtime of a directory, (as previously stored with
\r
1035 + * Get the mtime of a directory, (as previously stored with
\r
1036 * notmuch_directory_set_mtime).
\r
1038 * Returns 0 if no mtime has previously been stored for this
\r
1043 notmuch_directory_get_mtime (notmuch_directory_t *directory);
\r
1045 -/* Get a notmuch_filenames_t iterator listing all the filenames of
\r
1047 + * Get a notmuch_filenames_t iterator listing all the filenames of
\r
1048 * messages in the database within the given directory.
\r
1050 * The returned filenames will be the basename-entries only (not
\r
1051 - * complete paths). */
\r
1052 + * complete paths).
\r
1054 notmuch_filenames_t *
\r
1055 notmuch_directory_get_child_files (notmuch_directory_t *directory);
\r
1057 -/* Get a notmuch_filenams_t iterator listing all the filenames of
\r
1059 + * Get a notmuch_filenams_t iterator listing all the filenames of
\r
1060 * sub-directories in the database within the given directory.
\r
1062 * The returned filenames will be the basename-entries only (not
\r
1063 - * complete paths). */
\r
1064 + * complete paths).
\r
1066 notmuch_filenames_t *
\r
1067 notmuch_directory_get_child_directories (notmuch_directory_t *directory);
\r
1069 -/* Destroy a notmuch_directory_t object. */
\r
1071 + * Destroy a notmuch_directory_t object.
\r
1074 notmuch_directory_destroy (notmuch_directory_t *directory);
\r
1076 -/* Is the given 'filenames' iterator pointing at a valid filename.
\r
1078 + * Is the given 'filenames' iterator pointing at a valid filename.
\r
1080 * When this function returns TRUE, notmuch_filenames_get will return
\r
1081 * a valid string. Whereas when this function returns FALSE,
\r
1082 @@ -1436,7 +1587,8 @@ notmuch_directory_destroy (notmuch_directory_t *directory);
\r
1084 notmuch_filenames_valid (notmuch_filenames_t *filenames);
\r
1086 -/* Get the current filename from 'filenames' as a string.
\r
1088 + * Get the current filename from 'filenames' as a string.
\r
1090 * Note: The returned string belongs to 'filenames' and has a lifetime
\r
1091 * identical to it (and the directory to which it ultimately belongs).
\r
1092 @@ -1447,7 +1599,8 @@ notmuch_filenames_valid (notmuch_filenames_t *filenames);
\r
1094 notmuch_filenames_get (notmuch_filenames_t *filenames);
\r
1096 -/* Move the 'filenames' iterator to the next filename.
\r
1098 + * Move the 'filenames' iterator to the next filename.
\r
1100 * If 'filenames' is already pointing at the last filename then the
\r
1101 * iterator will be moved to a point just beyond that last filename,
\r
1102 @@ -1460,7 +1613,8 @@ notmuch_filenames_get (notmuch_filenames_t *filenames);
\r
1104 notmuch_filenames_move_to_next (notmuch_filenames_t *filenames);
\r
1106 -/* Destroy a notmuch_filenames_t object.
\r
1108 + * Destroy a notmuch_filenames_t object.
\r
1110 * It's not strictly necessary to call this function. All memory from
\r
1111 * the notmuch_filenames_t object will be reclaimed when the
\r
1112 @@ -1472,6 +1626,8 @@ notmuch_filenames_move_to_next (notmuch_filenames_t *filenames);
\r
1114 notmuch_filenames_destroy (notmuch_filenames_t *filenames);
\r