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 "gsimpleasyncresult.h"
  31 #include "gioenumtypes.h"
  32 #include "glibintl.h"
  33
  34
  35 /**
  36  * SECTION:gtlsinteraction
  37  * @short_description: Interaction with the user during TLS operations.
  38  * @include: gio/gio.h
  39  *
  40  * #GTlsInteraction provides a mechanism for the TLS connection and database
  41  * code to interact with the user. It can be used to ask the user for passwords.
  42  *
  43  * To use a #GTlsInteraction with a TLS connection use
  44  * g_tls_connection_set_interaction().
  45  *
  46  * Callers should instantiate a subclass of this that implements all the
  47  * various callbacks to show the required dialogs, such as
  48  * #GtkTlsInteraction. If no interaction is desired, usually %NULL can be
  49  * passed, see each method taking a #GTlsInteraction for details.
  50  */
  51
  52 /**
  53  * GTlsInteraction:
  54  *
  55  * An object representing interaction that the TLS connection and database
  56  * might have with the user.
  57  *
  58  * Since: 2.30
  59  */
  60
  61 /**
  62  * GTlsInteractionClass:
  63  *
  64  * The class for #GTlsInteraction.
  65  *
  66  * Since: 2.30
  67  */
  68
  69 G_DEFINE_TYPE (GTlsInteraction, g_tls_interaction, G_TYPE_OBJECT);
  70
  71 GTlsInteractionResult
  72 g_tls_interaction_default_ask_password (GTlsInteraction    *interaction,
  73                                         GTlsPassword       *password)
  74 {
  75   return G_TLS_INTERACTION_UNHANDLED;
  76 }
  77
  78 void
  79 g_tls_interaction_default_ask_password_async (GTlsInteraction    *interaction,
  80                                               GTlsPassword       *password,
  81                                               GAsyncReadyCallback callback,
  82                                               gpointer            user_data)
  83 {
  84   GSimpleAsyncResult *res;
  85
  86   res = g_simple_async_result_new (G_OBJECT (interaction), callback, user_data,
  87                                    g_tls_interaction_default_ask_password);
  88   g_simple_async_result_complete_in_idle (res);
  89   g_object_unref (res);
  90 }
  91
  92 GTlsInteractionResult
  93 g_tls_interaction_default_ask_password_finish (GTlsInteraction    *interaction,
  94                                                GAsyncResult       *result)
  95 {
  96   g_return_val_if_fail (g_simple_async_result_is_valid (result, G_OBJECT (interaction),
  97                         g_tls_interaction_default_ask_password), G_TLS_INTERACTION_UNHANDLED);
  98   return G_TLS_INTERACTION_UNHANDLED;
  99 }
 100
 101 static void
 102 g_tls_interaction_init (GTlsInteraction *interaction)
 103 {
 104 }
 105
 106 static void
 107 g_tls_interaction_class_init (GTlsInteractionClass *klass)
 108 {
 109   klass->ask_password = g_tls_interaction_default_ask_password;
 110   klass->ask_password_async = g_tls_interaction_default_ask_password_async;
 111   klass->ask_password_finish = g_tls_interaction_default_ask_password_finish;
 112 }
 113
 114 /**
 115  * g_tls_interaction_ask_password:
 116  * @interaction: a #GTlsInteraction object
 117  * @password: a #GTlsPassword object
 118  *
 119  * This function is normally called by #GTlsConnection or #GTlsDatabase to
 120  * ask the user for a password.
 121  *
 122  * Derived subclasses usually implement a password prompt, although they may
 123  * also choose to provide a password from elsewhere. The @password value will
 124  * be filled in and then @callback will be called. Alternatively the user may
 125  * abort this password request, which will usually abort the TLS connection.
 126  *
 127  * Returns: The status of the ask password interaction.
 128  *
 129  * Since: 2.30
 130  */
 131 GTlsInteractionResult
 132 g_tls_interaction_ask_password (GTlsInteraction    *interaction,
 133                                 GTlsPassword       *password)
 134 {
 135   g_return_val_if_fail (G_IS_TLS_INTERACTION (interaction), G_TLS_INTERACTION_UNHANDLED);
 136   g_return_val_if_fail (G_IS_TLS_PASSWORD (password), G_TLS_INTERACTION_UNHANDLED);
 137   return G_TLS_INTERACTION_GET_CLASS (interaction)->ask_password (interaction, password);
 138 }
 139
 140 /**
 141  * g_tls_interaction_ask_password_async:
 142  * @interaction: a #GTlsInteraction object
 143  * @password: a #GTlsPassword object
 144  * @callback: will be called when the interaction completes
 145  * @user_data: (allow-none): data to pass to the @callback
 146  *
 147  * This function is normally called by #GTlsConnection or #GTlsDatabase to
 148  * ask the user for a password.
 149  *
 150  * Derived subclasses usually implement a password prompt, although they may
 151  * also choose to provide a password from elsewhere. The @password value will
 152  * be filled in and then @callback will be called. Alternatively the user may
 153  * abort this password request, which will usually abort the TLS connection.
 154  *
 155  * The @callback will be invoked on thread-default main context of the thread
 156  * that called this function. The @callback should call
 157  * g_tls_interaction_ask_password_finish() to get the status of the user
 158  * interaction.
 159  *
 160  * Since: 2.30
 161  */
 162 void
 163 g_tls_interaction_ask_password_async (GTlsInteraction    *interaction,
 164                                       GTlsPassword       *password,
 165                                       GAsyncReadyCallback callback,
 166                                       gpointer            user_data)
 167 {
 168   g_return_if_fail (G_IS_TLS_INTERACTION (interaction));
 169   g_return_if_fail (G_IS_TLS_PASSWORD (password));
 170   g_return_if_fail (callback != NULL);
 171   G_TLS_INTERACTION_GET_CLASS (interaction)->ask_password_async (interaction, password,
 172                                                                  callback, user_data);
 173 }
 174
 175 /**
 176  * g_tls_interaction_ask_password_finish:
 177  * @interaction: a #GTlsInteraction object
 178  * @result: the result passed to the callback
 179  *
 180  * Complete an ask password user interaction request. This should be once
 181  * the g_tls_interaction_ask_password() completion callback is called.
 182  *
 183  * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed
 184  * to g_tls_interaction_ask_password() will have its password filled in.
 185  *
 186  * Returns: The status of the ask password interaction.
 187  *
 188  * Since: 2.30
 189  */
 190 GTlsInteractionResult
 191 g_tls_interaction_ask_password_finish (GTlsInteraction    *interaction,
 192                                        GAsyncResult       *result)
 193 {
 194   g_return_val_if_fail (G_IS_TLS_INTERACTION (interaction), G_TLS_INTERACTION_UNHANDLED);
 195   g_return_val_if_fail (G_IS_ASYNC_RESULT (result), G_TLS_INTERACTION_UNHANDLED);
 196   return G_TLS_INTERACTION_GET_CLASS (interaction)->ask_password_finish (interaction, result);
 197 }