--- /dev/null
+Return-Path: <amdragon@mit.edu>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+ by olra.theworths.org (Postfix) with ESMTP id 36F8F431FDC\r
+ for <notmuch@notmuchmail.org>; Mon, 25 Aug 2014 10:26:36 -0700 (PDT)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Spam-Flag: NO\r
+X-Spam-Score: -2.3\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=-2.3 tagged_above=-999 required=5\r
+ tests=[RCVD_IN_DNSWL_MED=-2.3] autolearn=disabled\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+ by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+ with ESMTP id 5xrPyhn+kJo1 for <notmuch@notmuchmail.org>;\r
+ Mon, 25 Aug 2014 10:26:31 -0700 (PDT)\r
+Received: from dmz-mailsec-scanner-7.mit.edu (dmz-mailsec-scanner-7.mit.edu\r
+ [18.7.68.36])\r
+ (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))\r
+ (No client certificate requested)\r
+ by olra.theworths.org (Postfix) with ESMTPS id 64BEA431FBF\r
+ for <notmuch@notmuchmail.org>; Mon, 25 Aug 2014 10:26:21 -0700 (PDT)\r
+X-AuditID: 12074424-f79346d000004923-4f-53fb71bc9962\r
+Received: from mailhub-auth-1.mit.edu ( [18.9.21.35])\r
+ (using TLS with cipher AES256-SHA (256/256 bits))\r
+ (Client did not present a certificate)\r
+ by dmz-mailsec-scanner-7.mit.edu (Symantec Messaging Gateway) with SMTP\r
+ id 97.99.18723.DB17BF35; Mon, 25 Aug 2014 13:26:21 -0400 (EDT)\r
+Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11])\r
+ by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id s7PHQJFa007819; \r
+ Mon, 25 Aug 2014 13:26:19 -0400\r
+Received: from drake.dyndns.org (31-35-14.wireless.csail.mit.edu\r
+ [128.31.35.14]) (authenticated bits=0)\r
+ (User authenticated as amdragon@ATHENA.MIT.EDU)\r
+ by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id s7PHQC7Y029625\r
+ (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);\r
+ Mon, 25 Aug 2014 13:26:18 -0400\r
+Received: from amthrax by drake.dyndns.org with local (Exim 4.77)\r
+ (envelope-from <amdragon@mit.edu>)\r
+ id 1XLy20-0003jo-2T; Mon, 25 Aug 2014 13:26:12 -0400\r
+From: Austin Clements <amdragon@mit.edu>\r
+To: notmuch@notmuchmail.org\r
+Subject: [PATCH v4 11/11] lib: Update doc of notmuch_database_{needs_upgrade,\r
+ upgrade}\r
+Date: Mon, 25 Aug 2014 13:26:09 -0400\r
+Message-Id: <1408987569-14146-12-git-send-email-amdragon@mit.edu>\r
+X-Mailer: git-send-email 2.0.0\r
+In-Reply-To: <1408987569-14146-1-git-send-email-amdragon@mit.edu>\r
+References: <1408987569-14146-1-git-send-email-amdragon@mit.edu>\r
+X-Brightmail-Tracker:\r
+ H4sIAAAAAAAAA+NgFjrGIsWRmVeSWpSXmKPExsUixCmqrLu38HewwdT/LBY3WrsZLZqmO1tc\r
+ vzmT2YHZ49b91+wez1bdYvbYcug9cwBzFJdNSmpOZllqkb5dAlfG4pZG5oLNghXHni5la2Cc\r
+ zdfFyMkhIWAiceDnTHYIW0ziwr31bF2MXBxCArOZJJadecYC4WxklDi7+CITSJWQwDEmiYe3\r
+ kyAScxkl/n15wwiSYBPQkPh9azFYkYiAtMTOu7NZQWxmAS+JZRf6wWxhgVCJ+Qf/g9WwCKhK\r
+ HFx6jg3E5hVwlGhc8IgF4gw5iYYbn8DinEDx6QtnQy12kPh++TzzBEb+BYwMqxhlU3KrdHMT\r
+ M3OKU5N1i5MT8/JSi3TN9XIzS/RSU0o3MYKCi91FZQdj8yGlQ4wCHIxKPLw34n8HC7EmlhVX\r
+ 5h5ilORgUhLlnZYPFOJLyk+pzEgszogvKs1JLT7EKMHBrCTC2wyS401JrKxKLcqHSUlzsCiJ\r
+ 8761tgoWEkhPLEnNTk0tSC2CycpwcChJ8N4vAGoULEpNT61Iy8wpQUgzcXCCDOcBGh4PUsNb\r
+ XJCYW5yZDpE/xagoJc77HyQhAJLIKM2D64VF/ytGcaBXhHmPglTxABMHXPcroMFMQINNe36C\r
+ DC5JREhJNTA2SnRPKyjaLVukeuLJs2K7Sbe2F8tfM074UnWRa3q576rdwhfSq24qSkyNNP2V\r
+ 8Pm7c6XMqk+F4frF//fpJK+PudlmXeC2xdr4zrtK/RP/dH494dRJ7Zg/deuR75o8s4PK1v37\r
+ lma5Uu6DWXPAuhlOJXrva+yPhiycrBzge7rljeWMhRmFBuZKLMUZiYZazEXFiQCzHfSk2QIA AA==\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.13\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+ <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Mon, 25 Aug 2014 17:26:36 -0000\r
+\r
+Clients are no longer required to call these functions after opening a\r
+database in read/write mode (which is good, because almost none of\r
+them do!).\r
+---\r
+ lib/notmuch.h | 23 ++++++++++++++---------\r
+ 1 file changed, 14 insertions(+), 9 deletions(-)\r
+\r
+diff --git a/lib/notmuch.h b/lib/notmuch.h\r
+index cbf2ba5..21a5225 100644\r
+--- a/lib/notmuch.h\r
++++ b/lib/notmuch.h\r
+@@ -352,22 +352,27 @@ unsigned int\r
+ notmuch_database_get_version (notmuch_database_t *database);\r
+ \r
+ /**\r
+- * Does this database need to be upgraded before writing to it?\r
++ * Can the database be upgraded to a newer database version?\r
+ *\r
+- * If this function returns TRUE then no functions that modify the\r
+- * database (notmuch_database_add_message, notmuch_message_add_tag,\r
+- * notmuch_directory_set_mtime, etc.) will work unless the function\r
+- * notmuch_database_upgrade is called successfully first.\r
++ * If this function returns TRUE, then the caller may call\r
++ * notmuch_database_upgrade to upgrade the database. If the caller\r
++ * does not upgrade an out-of-date database, then some functions may\r
++ * fail with NOTMUCH_STATUS_UPGRADE_REQUIRED. This always returns\r
++ * FALSE for a read-only database because there's no way to upgrade a\r
++ * read-only database.\r
+ */\r
+ notmuch_bool_t\r
+ notmuch_database_needs_upgrade (notmuch_database_t *database);\r
+ \r
+ /**\r
+- * Upgrade the current database.\r
++ * Upgrade the current database to the latest supported version.\r
+ *\r
+- * After opening a database in read-write mode, the client should\r
+- * check if an upgrade is needed (notmuch_database_needs_upgrade) and\r
+- * if so, upgrade with this function before making any modifications.\r
++ * This ensures that all current notmuch functionality will be\r
++ * available on the database. After opening a database in read-write\r
++ * mode, it is recommended that clients check if an upgrade is needed\r
++ * (notmuch_database_needs_upgrade) and if so, upgrade with this\r
++ * function before making any modifications. If\r
++ * notmuch_database_needs_upgrade returns FALSE, this will be a no-op.\r
+ *\r
+ * The optional progress_notify callback can be used by the caller to\r
+ * provide progress indication to the user. If non-NULL it will be\r
+-- \r
+2.0.0\r
+\r
projects / notmuch-archives.git / commitdiff