gio/gtlsinteraction.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright (C) 2011 Collabora, Ltd.
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General
  16  * Public License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  *
  20  * Author: Stef Walter <stefw@collabora.co.uk>
  21  */
  22
  23 #include "config.h"
  24
  25 #include <string.h>
  26
  27 #include "gtlsinteraction.h"
  28 #include "gtlspassword.h"
  29 #include "gasyncresult.h"
  30 #include "gcancellable.h"
  31 #include "gsimpleasyncresult.h"
  32 #include "gioenumtypes.h"
  33 #include "glibintl.h"
  34
  35
  36 /**
  37  * SECTION:gtlsinteraction
  38  * @short_description: Interaction with the user during TLS operations.
  39  * @include: gio/gio.h
  40  *
  41  * #GTlsInteraction provides a mechanism for the TLS connection and database
  42  * code to interact with the user. It can be used to ask the user for passwords.
  43  *
  44  * To use a #GTlsInteraction with a TLS connection use
  45  * g_tls_connection_set_interaction().
  46  *
  47  * Callers should instantiate a subclass of this that implements all the
  48  * various callbacks to show the required dialogs, such as
  49  * #GtkTlsInteraction. If no interaction is desired, usually %NULL can be
  50  * passed, see each method taking a #GTlsInteraction for details.
  51  */
  52
  53 /**
  54  * GTlsInteraction:
  55  *
  56  * An object representing interaction that the TLS connection and database
  57  * might have with the user.
  58  *
  59  * Since: 2.30
  60  */
  61
  62 /**
  63  * GTlsInteractionClass:
  64  *
  65  * The class for #GTlsInteraction.
  66  *
  67  * Since: 2.30
  68  */
  69
  70 G_DEFINE_TYPE (GTlsInteraction, g_tls_interaction, G_TYPE_OBJECT);
  71
  72 static GTlsInteractionResult
  73 g_tls_interaction_default_ask_password (GTlsInteraction    *interaction,
  74                                         GTlsPassword       *password,
  75                                         GCancellable       *cancellable,
  76                                         GError            **error)
  77 {
  78   if (g_cancellable_set_error_if_cancelled (cancellable, error))
  79     return G_TLS_INTERACTION_FAILED;
  80   else
  81     return G_TLS_INTERACTION_UNHANDLED;
  82 }
  83
  84 static void
  85 g_tls_interaction_default_ask_password_async (GTlsInteraction    *interaction,
  86                                               GTlsPassword       *password,
  87                                               GCancellable       *cancellable,
  88                                               GAsyncReadyCallback callback,
  89                                               gpointer            user_data)
  90 {
  91   GSimpleAsyncResult *res;
  92   GError *error = NULL;
  93
  94   res = g_simple_async_result_new (G_OBJECT (interaction), callback, user_data,
  95                                    g_tls_interaction_default_ask_password);
  96   if (g_cancellable_set_error_if_cancelled (cancellable, &error))
  97     g_simple_async_result_take_error (res, error);
  98   g_simple_async_result_complete_in_idle (res);
  99   g_object_unref (res);
 100 }
 101
 102 static GTlsInteractionResult
 103 g_tls_interaction_default_ask_password_finish (GTlsInteraction    *interaction,
 104                                                GAsyncResult       *result,
 105                                                GError            **error)
 106 {
 107   g_return_val_if_fail (g_simple_async_result_is_valid (result, G_OBJECT (interaction),
 108                         g_tls_interaction_default_ask_password), G_TLS_INTERACTION_UNHANDLED);
 109
 110   if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result), error))
 111     return G_TLS_INTERACTION_FAILED;
 112
 113   return G_TLS_INTERACTION_UNHANDLED;
 114 }
 115
 116 static void
 117 g_tls_interaction_init (GTlsInteraction *interaction)
 118 {
 119 }
 120
 121 static void
 122 g_tls_interaction_class_init (GTlsInteractionClass *klass)
 123 {
 124   klass->ask_password = g_tls_interaction_default_ask_password;
 125   klass->ask_password_async = g_tls_interaction_default_ask_password_async;
 126   klass->ask_password_finish = g_tls_interaction_default_ask_password_finish;
 127 }
 128
 129 /**
 130  * g_tls_interaction_ask_password:
 131  * @interaction: a #GTlsInteraction object
 132  * @password: a #GTlsPassword object
 133  * @cancellable: an optional #GCancellable cancellation object
 134  * @error: an optional location to place an error on failure
 135  *
 136  * This function is normally called by #GTlsConnection or #GTlsDatabase to
 137  * ask the user for a password.
 138  *
 139  * Derived subclasses usually implement a password prompt, although they may
 140  * also choose to provide a password from elsewhere. The @password value will
 141  * be filled in and then @callback will be called. Alternatively the user may
 142  * abort this password request, which will usually abort the TLS connection.
 143  *
 144  * If the interaction is cancelled by the cancellation object, or by the
 145  * user then %G_TLS_INTERACTION_ABORTED will be returned. Certain
 146  * implementations may not support immediate cancellation.
 147  *
 148  * Returns: The status of the ask password interaction.
 149  *
 150  * Since: 2.30
 151  */
 152 GTlsInteractionResult
 153 g_tls_interaction_ask_password (GTlsInteraction    *interaction,
 154                                 GTlsPassword       *password,
 155                                 GCancellable       *cancellable,
 156                                 GError            **error)
 157 {
 158   g_return_val_if_fail (G_IS_TLS_INTERACTION (interaction), G_TLS_INTERACTION_UNHANDLED);
 159   g_return_val_if_fail (G_IS_TLS_PASSWORD (password), G_TLS_INTERACTION_UNHANDLED);
 160   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), G_TLS_INTERACTION_UNHANDLED);
 161   return G_TLS_INTERACTION_GET_CLASS (interaction)->ask_password (interaction,
 162                                                                   password,
 163                                                                   cancellable,
 164                                                                   error);
 165 }
 166
 167 /**
 168  * g_tls_interaction_ask_password_async:
 169  * @interaction: a #GTlsInteraction object
 170  * @password: a #GTlsPassword object
 171  * @cancellable: an optional #GCancellable cancellation object
 172  * @callback: (allow-none): will be called when the interaction completes
 173  * @user_data: (allow-none): data to pass to the @callback
 174  *
 175  * This function is normally called by #GTlsConnection or #GTlsDatabase to
 176  * ask the user for a password.
 177  *
 178  * Derived subclasses usually implement a password prompt, although they may
 179  * also choose to provide a password from elsewhere. The @password value will
 180  * be filled in and then @callback will be called. Alternatively the user may
 181  * abort this password request, which will usually abort the TLS connection.
 182  *
 183  * The @callback will be invoked on thread-default main context of the thread
 184  * that called this function. The @callback should call
 185  * g_tls_interaction_ask_password_finish() to get the status of the user
 186  * interaction.
 187  *
 188  * Certain implementations may not support immediate cancellation.
 189  *
 190  * Since: 2.30
 191  */
 192 void
 193 g_tls_interaction_ask_password_async (GTlsInteraction    *interaction,
 194                                       GTlsPassword       *password,
 195                                       GCancellable       *cancellable,
 196                                       GAsyncReadyCallback callback,
 197                                       gpointer            user_data)
 198 {
 199   g_return_if_fail (G_IS_TLS_INTERACTION (interaction));
 200   g_return_if_fail (G_IS_TLS_PASSWORD (password));
 201   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
 202   G_TLS_INTERACTION_GET_CLASS (interaction)->ask_password_async (interaction, password,
 203                                                                  cancellable,
 204                                                                  callback, user_data);
 205 }
 206
 207 /**
 208  * g_tls_interaction_ask_password_finish:
 209  * @interaction: a #GTlsInteraction object
 210  * @result: the result passed to the callback
 211  * @error: an optional location to place an error on failure
 212  *
 213  * Complete an ask password user interaction request. This should be once
 214  * the g_tls_interaction_ask_password() completion callback is called.
 215  *
 216  * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed
 217  * to g_tls_interaction_ask_password() will have its password filled in.
 218  *
 219  * If the interaction is cancelled by the cancellation object, or by the
 220  * user then %G_TLS_INTERACTION_ABORTED will be returned.
 221  *
 222  * Returns: The status of the ask password interaction.
 223  *
 224  * Since: 2.30
 225  */
 226 GTlsInteractionResult
 227 g_tls_interaction_ask_password_finish (GTlsInteraction    *interaction,
 228                                        GAsyncResult       *result,
 229                                        GError            **error)
 230 {
 231   g_return_val_if_fail (G_IS_TLS_INTERACTION (interaction), G_TLS_INTERACTION_UNHANDLED);
 232   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), G_TLS_INTERACTION_UNHANDLED);
 233   return G_TLS_INTERACTION_GET_CLASS (interaction)->ask_password_finish (interaction,
 234                                                                          result,
 235                                                                          error);
 236 }