libebackend/e-user-prompter-server-extension.c

   1 /*
   2  * e-user-prompter-server-extension.c
   3  *
   4  * This library is free software you can redistribute it and/or modify it
   5  * under the terms of the GNU Lesser General Public License as published by
   6  * the Free Software Foundation.
   7  *
   8  * This library is distributed in the hope that it will be useful, but
   9  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  10  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  11  * for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public License
  14  * along with this library; if not, see <http://www.gnu.org/licenses/>.
  15  *
  16  */
  17
  18 /**
  19  * SECTION: e-user-prompter-server-extension
  20  * @short_description: Extension for a server-side user prompter
  21  *
  22  * The #EUserPrompterServerExtension is a base struct for extension
  23  * of EUserPrompterServer, to provide customized or specialized dialog
  24  * prompts.
  25  *
  26  * A descendant defines two virtual functions,
  27  * the EUserPrompterServerExtensionClass::register_dialogs which is used as
  28  * a convenient function, where the descendant registers all the dialogs it
  29  * provides on the server with e_user_prompter_server_register().
  30  *
  31  * The next function is EUserPrompterServerExtensionClass::prompt, which is
  32  * used to initiate user prompt. The implementor should not block main thread
  33  * with this function, because this is treated fully asynchronously.
  34  * User's response is passed to the server with
  35  * e_user_prompter_server_extension_response() call.
  36  **/
  37
  38 #ifdef HAVE_CONFIG_H
  39 #include <config.h>
  40 #endif /* HAVE_CONFIG_H */
  41
  42 #include <string.h>
  43
  44 #include "e-user-prompter-server-extension.h"
  45
  46 #define E_USER_PROMPTER_SERVER_EXTENSION_GET_PRIVATE(obj) \
  47         (G_TYPE_INSTANCE_GET_PRIVATE \
  48         ((obj), E_TYPE_USER_PROMPTER_SERVER_EXTENSION, EUserPrompterServerExtensionPrivate))
  49
  50 struct _EUserPrompterServerExtensionPrivate {
  51         gint dummy; /* not used */
  52 };
  53
  54 G_DEFINE_ABSTRACT_TYPE (EUserPrompterServerExtension, e_user_prompter_server_extension, E_TYPE_EXTENSION)
  55
  56 static void
  57 user_prompter_server_extension_constructed (GObject *object)
  58 {
  59         EExtensible *extensible;
  60         EUserPrompterServer *server;
  61         EExtension *extension;
  62         EUserPrompterServerExtensionClass *klass;
  63
  64         /* Chain up to parent's constructed() method. */
  65         G_OBJECT_CLASS (e_user_prompter_server_extension_parent_class)->constructed (object);
  66
  67         g_return_if_fail (E_IS_USER_PROMPTER_SERVER_EXTENSION (object));
  68
  69         extension = E_EXTENSION (object);
  70         g_return_if_fail (extension != NULL);
  71
  72         extensible = e_extension_get_extensible (extension);
  73         g_return_if_fail (E_IS_USER_PROMPTER_SERVER (extensible));
  74
  75         server = E_USER_PROMPTER_SERVER (extensible);
  76
  77         klass = E_USER_PROMPTER_SERVER_EXTENSION_GET_CLASS (extension);
  78         g_return_if_fail (klass->register_dialogs);
  79
  80         klass->register_dialogs (extension, server);
  81 }
  82
  83 static void
  84 e_user_prompter_server_extension_class_init (EUserPrompterServerExtensionClass *class)
  85 {
  86         GObjectClass *object_class;
  87         EExtensionClass *extension_class;
  88
  89         g_type_class_add_private (class, sizeof (EUserPrompterServerExtensionPrivate));
  90
  91         class->register_dialogs = NULL;
  92         class->prompt = NULL;
  93
  94         object_class = G_OBJECT_CLASS (class);
  95         object_class->constructed = user_prompter_server_extension_constructed;
  96
  97         extension_class = E_EXTENSION_CLASS (class);
  98         extension_class->extensible_type = E_TYPE_USER_PROMPTER_SERVER;
  99 }
 100
 101 static void
 102 e_user_prompter_server_extension_init (EUserPrompterServerExtension *extension)
 103 {
 104         extension->priv = E_USER_PROMPTER_SERVER_EXTENSION_GET_PRIVATE (extension);
 105 }
 106
 107 /**
 108  * e_user_prompter_server_extension_prompt:
 109  * @extension: an #EUserPrompterServerExtension
 110  * @prompt_id: Prompt identificator, which is used in call to e_user_prompter_server_extension_response()
 111  * @dialog_name: Name of a dialog to run
 112  * @parameters: (allow-none): Optional extension parameters for the dialog, as passed by a caller
 113  *
 114  * Instructs extension to show dialog @dialog_name. If it cannot be found,
 115  * or any error, then return %FALSE. The caller can pass optional @parameters,
 116  * if @extension uses any. Meaning of @parameters is known only to the caller
 117  * and to the dialog implementor, it's not interpretted nor checked for correctness
 118  * in any way in #EUserPrompterServer. The only limitation of @parameters is that
 119  * the array elements are strings.
 120  *
 121  * The @prompt_id is used as an identificator of the prompt itself,
 122  * and is used in e_user_prompter_server_extension_response() call,
 123  * which finishes the prompt.
 124  *
 125  * Note: The function call should not block main loop, it should
 126  * just show dialog and return.
 127  *
 128  * Returns: Whether dialog was found and shown.
 129  *
 130  * Since: 3.8
 131  **/
 132 gboolean
 133 e_user_prompter_server_extension_prompt (EUserPrompterServerExtension *extension,
 134                                          gint prompt_id,
 135                                          const gchar *dialog_name,
 136                                          const ENamedParameters *parameters)
 137 {
 138         EUserPrompterServerExtensionClass *klass;
 139
 140         g_return_val_if_fail (E_IS_USER_PROMPTER_SERVER_EXTENSION (extension), FALSE);
 141
 142         klass = E_USER_PROMPTER_SERVER_EXTENSION_GET_CLASS (extension);
 143         g_return_val_if_fail (klass->prompt != NULL, FALSE);
 144
 145         return klass->prompt (extension, prompt_id, dialog_name, parameters);
 146 }
 147
 148 /**
 149  * e_user_prompter_server_extension_response:
 150  * @extension: an #EUserPrompterServerExtension
 151  * @prompt_id: Prompt identificator
 152  * @response: Response of the prompt
 153  * @values: (allow-none): Additional response values, if extension defines any
 154  *
 155  * A conveniente wrapper function around e_user_prompter_server_response(),
 156  * which ends previous call of e_user_prompter_server_extension_prompt().
 157  * The @response and @values is known only to the caller and to the dialog implementor,
 158  * it's not interpretted nor checked for correctness in any way in #EUserPrompterServer.
 159  * The only limitation of @values is that the array elements are strings.
 160  *
 161  * Since: 3.8
 162  **/
 163 void
 164 e_user_prompter_server_extension_response (EUserPrompterServerExtension *extension,
 165                                            gint prompt_id,
 166                                            gint response,
 167                                            const ENamedParameters *values)
 168 {
 169         EExtensible *extensible;
 170         EUserPrompterServer *server;
 171
 172         g_return_if_fail (E_IS_USER_PROMPTER_SERVER_EXTENSION (extension));
 173
 174         extensible = e_extension_get_extensible (E_EXTENSION (extension));
 175         g_return_if_fail (E_IS_USER_PROMPTER_SERVER (extensible));
 176
 177         server = E_USER_PROMPTER_SERVER (extensible);
 178
 179         e_user_prompter_server_response (server, prompt_id, response, values);
 180 }