[geary/mjog/user-plugins: 16/26] Add stable public interfaces for plugins to use

[Michael Gratton <mjog src gnome org>]

commit f72b1354f828dcdf513cf06b89109fabf194aa66
Author: Michael Gratton <mike vee net>
Date:   Tue Mar 10 12:46:23 2020 +1100

    Add stable public interfaces for plugins to use
    
    These interfaces provide a stable, public API for plugins that can
    provide API stability while the underlying client and engine APIs
    change.

 po/POTFILES.in                              |  7 ++++
 src/client/meson.build                      |  7 ++++
 src/client/plugin/plugin-account.vala       | 21 ++++++++++++
 src/client/plugin/plugin-application.vala   | 20 +++++++++++
 src/client/plugin/plugin-contact-store.vala | 41 ++++++++++++++++++++++
 src/client/plugin/plugin-email-store.vala   | 27 +++++++++++++++
 src/client/plugin/plugin-email.vala         | 53 +++++++++++++++++++++++++++++
 src/client/plugin/plugin-folder-store.vala  | 32 +++++++++++++++++
 src/client/plugin/plugin-folder.vala        | 40 ++++++++++++++++++++++
 9 files changed, 248 insertions(+)
---
diff --git a/po/POTFILES.in b/po/POTFILES.in
index 7c983e35..1a1db9c1 100644
--- a/po/POTFILES.in
+++ b/po/POTFILES.in
@@ -89,6 +89,13 @@ src/client/plugin/messaging-menu/messaging-menu.plugin.in
 src/client/plugin/messaging-menu/messaging-menu.vala
 src/client/plugin/notification-badge/notification-badge.plugin.in
 src/client/plugin/notification-badge/notification-badge.vala
+src/client/plugin/plugin-account.vala
+src/client/plugin/plugin-application.vala
+src/client/plugin/plugin-contact-store.vala
+src/client/plugin/plugin-email-store.vala
+src/client/plugin/plugin-email.vala
+src/client/plugin/plugin-folder-store.vala
+src/client/plugin/plugin-folder.vala
 src/client/plugin/plugin-notification.vala
 src/client/sidebar/sidebar-branch.vala
 src/client/sidebar/sidebar-common.vala
diff --git a/src/client/meson.build b/src/client/meson.build
index 1960dd48..847c8583 100644
--- a/src/client/meson.build
+++ b/src/client/meson.build
@@ -91,6 +91,13 @@ geary_client_vala_sources = files(
   'folder-list/folder-list-search-branch.vala',
   'folder-list/folder-list-special-grouping.vala',
 
+  'plugin/plugin-account.vala',
+  'plugin/plugin-application.vala',
+  'plugin/plugin-contact-store.vala',
+  'plugin/plugin-email-store.vala',
+  'plugin/plugin-email.vala',
+  'plugin/plugin-folder-store.vala',
+  'plugin/plugin-folder.vala',
   'plugin/plugin-notification.vala',
 
   'sidebar/sidebar-branch.vala',
diff --git a/src/client/plugin/plugin-account.vala b/src/client/plugin/plugin-account.vala
new file mode 100644
index 00000000..cf1fbf69
--- /dev/null
+++ b/src/client/plugin/plugin-account.vala
@@ -0,0 +1,21 @@
+/*
+ * Copyright © 2020 Michael Gratton <mike vee net>
+ *
+ * This software is licensed under the GNU Lesser General Public License
+ * (version 2.1 or later). See the COPYING file in this distribution.
+ */
+
+/**
+ * An object representing an account for use by plugins.
+ *
+ * Instances of these may be obtained from their respective {@link
+ * Folder} objects.
+ */
+public interface Plugin.Account : Geary.BaseObject {
+
+
+    /** Returns the human-readable name of this account. */
+    public abstract string display_name { get; }
+
+
+}
diff --git a/src/client/plugin/plugin-application.vala b/src/client/plugin/plugin-application.vala
new file mode 100644
index 00000000..20310785
--- /dev/null
+++ b/src/client/plugin/plugin-application.vala
@@ -0,0 +1,20 @@
+/*
+ * Copyright © 2020 Michael Gratton <mike vee net>
+ *
+ * This software is licensed under the GNU Lesser General Public License
+ * (version 2.1 or later). See the COPYING file in this distribution.
+ */
+
+/**
+ * An object representing the client application for use by plugins.
+ *
+ * Plugins may obtain instances of this object from their context
+ * objects, for example {@link
+ * Application.NotificationContext.get_application}.
+ */
+public interface Plugin.Application : Geary.BaseObject {
+
+
+    public abstract void show_folder(Folder folder);
+
+}
diff --git a/src/client/plugin/plugin-contact-store.vala b/src/client/plugin/plugin-contact-store.vala
new file mode 100644
index 00000000..395cbabb
--- /dev/null
+++ b/src/client/plugin/plugin-contact-store.vala
@@ -0,0 +1,41 @@
+/*
+ * Copyright © 2020 Michael Gratton <mike vee net>
+ *
+ * This software is licensed under the GNU Lesser General Public License
+ * (version 2.1 or later). See the COPYING file in this distribution.
+ */
+
+/**
+ * Provides plugins with access to contact information.
+ *
+ * Plugins may obtain instances of this object from their context
+ * objects, for example {@link
+ * Application.NotificationContext.get_contacts_for_folder}.
+ */
+public interface Plugin.ContactStore : Geary.BaseObject {
+
+
+    /** Searches for contacts based on a specific string */
+    public abstract async Gee.Collection<global::Application.Contact> search(
+        string query,
+        uint min_importance,
+        uint limit,
+        GLib.Cancellable? cancellable
+    ) throws GLib.Error;
+
+
+    /**
+     * Returns a contact for a specific mailbox.
+     *
+     * Returns a contact that has the given mailbox address listed as
+     * a primary or secondary email. A contact will always be
+     * returned, so if no matching contact already exists a new,
+     * non-persistent contact will be returned.
+     */
+    public abstract async global::Application.Contact load(
+        Geary.RFC822.MailboxAddress mailbox,
+        GLib.Cancellable? cancellable
+    ) throws GLib.Error;
+
+
+}
diff --git a/src/client/plugin/plugin-email-store.vala b/src/client/plugin/plugin-email-store.vala
new file mode 100644
index 00000000..35dc9c18
--- /dev/null
+++ b/src/client/plugin/plugin-email-store.vala
@@ -0,0 +1,27 @@
+/*
+ * Copyright © 2020 Michael Gratton <mike vee net>
+ *
+ * This software is licensed under the GNU Lesser General Public License
+ * (version 2.1 or later). See the COPYING file in this distribution.
+ */
+
+/**
+ * Provides plugins with access to email.
+ *
+ * Plugins may obtain instances of this object from their context
+ * objects, for example {@link
+ * Application.NotificationContext.get_email}.
+ */
+public interface Plugin.EmailStore : Geary.BaseObject {
+
+
+    /** Emitted when an email message has been sent. */
+    public signal void email_sent(Email message);
+
+    /** Returns a read-only set of all known folders. */
+    public async abstract Gee.Collection<Email> get_email(
+        Gee.Collection<EmailIdentifier> ids,
+        GLib.Cancellable? cancellable
+    ) throws GLib.Error;
+
+}
diff --git a/src/client/plugin/plugin-email.vala b/src/client/plugin/plugin-email.vala
new file mode 100644
index 00000000..8eb94ddb
--- /dev/null
+++ b/src/client/plugin/plugin-email.vala
@@ -0,0 +1,53 @@
+/*
+ * Copyright © 2020 Michael Gratton <mike vee net>
+ *
+ * This software is licensed under the GNU Lesser General Public License
+ * (version 2.1 or later). See the COPYING file in this distribution.
+ */
+
+/**
+ * An object representing an email for use by plugins.
+ *
+ * Instances of these may be obtained from {@link EmailStore}.
+ */
+public interface Plugin.Email : Geary.BaseObject {
+
+
+    /** Returns a unique identifier for this email. */
+    public abstract EmailIdentifier identifier { get; }
+
+    /** Returns the subject header value for the this email. */
+    public abstract string subject { get; }
+
+    /**
+     * Returns the email's primary originator.
+     *
+     * This method returns the mailbox of the best originator of the
+     * email, if any.
+     *
+     * @see Util.Email.get_primary_originator
+     */
+    public abstract Geary.RFC822.MailboxAddress? get_primary_originator();
+
+}
+
+
+// XXX this should be an inner interface of Email, but GNOME/vala#918
+// prevents that.
+
+/**
+ * An object representing an email's identifier.
+ */
+public interface Plugin.EmailIdentifier :
+    Geary.BaseObject, Gee.Hashable<EmailIdentifier> {
+
+    /**
+     * Returns a variant version of this identifier.
+     *
+     * This value is suitable to be used as the `show-email`
+     * application action parameter.
+     */
+    public abstract GLib.Variant to_variant();
+
+
+}
diff --git a/src/client/plugin/plugin-folder-store.vala b/src/client/plugin/plugin-folder-store.vala
new file mode 100644
index 00000000..982097e7
--- /dev/null
+++ b/src/client/plugin/plugin-folder-store.vala
@@ -0,0 +1,32 @@
+/*
+ * Copyright © 2020 Michael Gratton <mike vee net>
+ *
+ * This software is licensed under the GNU Lesser General Public License
+ * (version 2.1 or later). See the COPYING file in this distribution.
+ */
+
+/**
+ * Provides plugins with access to folders.
+ *
+ * Plugins may obtain instances of this object from their context
+ * objects, for example {@link
+ * Application.NotificationContext.get_folder_store}.
+ */
+public interface Plugin.FolderStore : Geary.BaseObject {
+
+
+    /** Emitted when new folders are available. */
+    public signal void folders_available(Gee.Collection<Folder> available);
+
+    /** Emitted when existing folders have become unavailable. */
+    public signal void folders_unavailable(Gee.Collection<Folder> unavailable);
+
+    /** Emitted when existing folders have become unavailable. */
+    public signal void folders_type_changed(Gee.Collection<Folder> changed);
+
+
+    /** Returns a read-only set of all known folders. */
+    public abstract Gee.Collection<Folder> get_folders();
+
+
+}
diff --git a/src/client/plugin/plugin-folder.vala b/src/client/plugin/plugin-folder.vala
new file mode 100644
index 00000000..0765dff1
--- /dev/null
+++ b/src/client/plugin/plugin-folder.vala
@@ -0,0 +1,40 @@
+/*
+ * Copyright © 2020 Michael Gratton <mike vee net>
+ *
+ * This software is licensed under the GNU Lesser General Public License
+ * (version 2.1 or later). See the COPYING file in this distribution.
+ */
+
+/**
+ * An object representing a folder for use by plugins.
+ *
+ * Instances of these may be obtained from {@link FolderStore}.
+ */
+public interface Plugin.Folder : Geary.BaseObject {
+
+
+    /**
+     * Returns a unique identifier for this account and folder.
+     *
+     * The value returned is persistent across application restarts.
+     */
+    public abstract string persistent_id { get; }
+
+    /** Returns the human-readable name of this folder. */
+    public abstract string display_name { get; }
+
+    /** Returns the type of this folder. */
+    public abstract Geary.SpecialFolderType folder_type { get; }
+
+    /** Returns the account the folder belongs to, if any. */
+    public abstract Account? account { get; }
+
+    /**
+     * Returns a variant identifying this account and folder.
+     *
+     * This value is suitable to be used as the `show-folder`
+     * application action parameter.
+     */
+    public abstract GLib.Variant to_variant();
+
+}