[geary] Add LIST RETURN functionality

[Jim Nelson <jnelson src gnome org>]

commit 7f535b02ecdaccffd0ab685fa4a8d8f888f1b3e0
Author: Jim Nelson <jim yorba org>
Date:   Thu Jan 30 14:59:17 2014 -0800

    Add LIST RETURN functionality
    
    SPECIAL-USE does not have to return special-use flags, but the
    LIST RETURN syntax can force it, which we want.

 po/POTFILES.in                                     |    1 +
 src/CMakeLists.txt                                 |    1 +
 src/console/main.vala                              |    2 +-
 src/engine/imap/api/imap-account.vala              |   11 +++++-
 src/engine/imap/command/imap-list-command.vala     |   15 +++++++-
 .../imap/command/imap-list-return-parameter.vala   |   36 ++++++++++++++++++++
 src/engine/imap/response/imap-capabilities.vala    |   10 +++++
 7 files changed, 71 insertions(+), 5 deletions(-)
---
diff --git a/po/POTFILES.in b/po/POTFILES.in
index 0044498..e59da6f 100644
--- a/po/POTFILES.in
+++ b/po/POTFILES.in
@@ -160,6 +160,7 @@ src/engine/imap/command/imap-fetch-command.vala
 src/engine/imap/command/imap-id-command.vala
 src/engine/imap/command/imap-idle-command.vala
 src/engine/imap/command/imap-list-command.vala
+src/engine/imap/command/imap-list-return-parameter.vala
 src/engine/imap/command/imap-login-command.vala
 src/engine/imap/command/imap-logout-command.vala
 src/engine/imap/command/imap-message-set.vala
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index f48b548..9c38bab 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -100,6 +100,7 @@ engine/imap/command/imap-fetch-command.vala
 engine/imap/command/imap-id-command.vala
 engine/imap/command/imap-idle-command.vala
 engine/imap/command/imap-list-command.vala
+engine/imap/command/imap-list-return-parameter.vala
 engine/imap/command/imap-login-command.vala
 engine/imap/command/imap-logout-command.vala
 engine/imap/command/imap-message-set.vala
diff --git a/src/console/main.vala b/src/console/main.vala
index a78dd8a..c5fa7df 100644
--- a/src/console/main.vala
+++ b/src/console/main.vala
@@ -443,7 +443,7 @@ class ImapConsole : Gtk.Window {
         
         status("Listing...");
         cx.send_async.begin(new Geary.Imap.ListCommand.wildcarded(args[0],
-            new Geary.Imap.MailboxSpecifier(args[1]), (cmd.down() == "xlist")), null, on_list);
+            new Geary.Imap.MailboxSpecifier(args[1]), (cmd.down() == "xlist"), null), null, on_list);
     }
     
     private void on_list(Object? source, AsyncResult result) {
diff --git a/src/engine/imap/api/imap-account.vala b/src/engine/imap/api/imap-account.vala
index 82aa491..388a882 100644
--- a/src/engine/imap/api/imap-account.vala
+++ b/src/engine/imap/api/imap-account.vala
@@ -302,9 +302,16 @@ private class Geary.Imap.Account : BaseObject {
         ClientSession session = yield claim_session_async(cancellable);
         bool can_xlist = session.capabilities.has_capability(Capabilities.XLIST);
         
+        // Request SPECIAL-USE if available and not using XLIST
+        ListReturnParameter? return_param = null;
+        if (session.capabilities.supports_special_use() && !can_xlist) {
+            return_param = new ListReturnParameter();
+            return_param.add_special_use();
+        }
+        
         ListCommand cmd;
         if (parent == null) {
-            cmd = new ListCommand.wildcarded("", new MailboxSpecifier("%"), can_xlist);
+            cmd = new ListCommand.wildcarded("", new MailboxSpecifier("%"), can_xlist, return_param);
         } else {
             string? specifier = parent.get_fullpath(null);
             string? delim = parent.get_root().default_separator;
@@ -315,7 +322,7 @@ private class Geary.Imap.Account : BaseObject {
             
             specifier += specifier.has_suffix(delim) ? "%" : (delim + "%");
             
-            cmd = new ListCommand(new MailboxSpecifier(specifier), can_xlist);
+            cmd = new ListCommand(new MailboxSpecifier(specifier), can_xlist, return_param);
         }
         
         Gee.List<MailboxInformation> list_results = new Gee.ArrayList<MailboxInformation>();
diff --git a/src/engine/imap/command/imap-list-command.vala b/src/engine/imap/command/imap-list-command.vala
index 2ae5020..cc2cb53 100644
--- a/src/engine/imap/command/imap-list-command.vala
+++ b/src/engine/imap/command/imap-list-command.vala
@@ -33,16 +33,27 @@ public class Geary.Imap.ListCommand : Command {
      *
      * See http://redmine.yorba.org/issues/7624 for more information.
      */
-    public ListCommand(MailboxSpecifier mailbox, bool use_xlist) {
+    public ListCommand(MailboxSpecifier mailbox, bool use_xlist, ListReturnParameter? return_param) {
         base (use_xlist ? XLIST_NAME : NAME, { "" });
         
         add(mailbox.to_parameter());
+        add_return_parameter(return_param);
     }
     
-    public ListCommand.wildcarded(string reference, MailboxSpecifier mailbox, bool use_xlist) {
+    public ListCommand.wildcarded(string reference, MailboxSpecifier mailbox, bool use_xlist,
+        ListReturnParameter? return_param) {
         base (use_xlist ? XLIST_NAME : NAME, { reference });
         
         add(mailbox.to_parameter());
+        add_return_parameter(return_param);
+    }
+    
+    private void add_return_parameter(ListReturnParameter? return_param) {
+        if (return_param == null || return_param.size == 0)
+            return;
+        
+        add(StringParameter.get_best_for("return"));
+        add(return_param);
     }
 }
 
diff --git a/src/engine/imap/command/imap-list-return-parameter.vala 
b/src/engine/imap/command/imap-list-return-parameter.vala
new file mode 100644
index 0000000..df88f87
--- /dev/null
+++ b/src/engine/imap/command/imap-list-return-parameter.vala
@@ -0,0 +1,36 @@
+/* Copyright 2014 Yorba Foundation
+ *
+ * This software is licensed under the GNU Lesser General Public License
+ * (version 2.1 or later).  See the COPYING file in this distribution.
+ */
+
+/**
+ * RETURN parameters for { link ListCommand}.
+ *
+ * LIST's extended syntax allows for special RETURN parameters to be included indicating additional
+ * information for the server to return as part of the LIST results.  ListReturnParameters allows
+ * for the well-known parameters to be easily generated and added to ListCommand.
+ *
+ * See the LIST-STATUS ([[https://tools.ietf.org/html/rfc5819]]) and SPECIAL-USE
+ * ([[https://tools.ietf.org/html/rfc6154]]) RFCs for examples of this in use.
+ */
+
+public class Geary.Imap.ListReturnParameter : ListParameter {
+    /**
+     * See https://tools.ietf.org/html/rfc6154
+     */
+    public const string SPECIAL_USE = "special-use";
+    
+    /**
+     * Creates an empty { link ListReturnParameter}.
+     *
+     * If passed in without additions, this will be ignored by { link ListCommand}.
+     */
+    public ListReturnParameter() {
+    }
+    
+    public void add_special_use() {
+        add(StringParameter.get_best_for(SPECIAL_USE));
+    }
+}
+
diff --git a/src/engine/imap/response/imap-capabilities.vala b/src/engine/imap/response/imap-capabilities.vala
index 3654a3f..8a6486b 100644
--- a/src/engine/imap/response/imap-capabilities.vala
+++ b/src/engine/imap/response/imap-capabilities.vala
@@ -11,6 +11,7 @@ public class Geary.Imap.Capabilities : Geary.GenericCapabilities {
     public const string COMPRESS = "COMPRESS";
     public const string DEFLATE_SETTING = "DEFLATE";
     public const string UIDPLUS = "UIDPLUS";
+    public const string SPECIAL_USE = "SPECIAL-USE";
     
     public const string NAME_SEPARATOR = "=";
     public const string? VALUE_SEPARATOR = null;
@@ -53,5 +54,14 @@ public class Geary.Imap.Capabilities : Geary.GenericCapabilities {
     public bool supports_uidplus() {
         return has_capability(UIDPLUS);
     }
+    
+    /**
+     * Indicates the { link ClientSession{ reported support for SPECIAL-USE.
+     *
+     * See [[https://tools.ietf.org/html/rfc6154]]
+     */
+    public bool supports_special_use() {
+        return has_capability(SPECIAL_USE);
+    }
 }