1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright (C) 2011 Collabora, Ltd.
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.
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.
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.
20 * Author: Stef Walter <stefw@collabora.co.uk>
27 #include "gtlsinteraction.h"
28 #include "gtlspassword.h"
29 #include "gasyncresult.h"
30 #include "gsimpleasyncresult.h"
31 #include "gioenumtypes.h"
36 * SECTION:gtlsinteraction
37 * @short_description: Interaction with the user during TLS operations.
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.
43 * To use a #GTlsInteraction with a TLS connection use
44 * g_tls_connection_set_interaction().
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.
55 * An object representing interaction that the TLS connection and database
56 * might have with the user.
62 * GTlsInteractionClass:
64 * The class for #GTlsInteraction.
69 G_DEFINE_TYPE (GTlsInteraction, g_tls_interaction, G_TYPE_OBJECT);
71 static GTlsInteractionResult
72 g_tls_interaction_default_ask_password (GTlsInteraction *interaction,
73 GTlsPassword *password)
75 return G_TLS_INTERACTION_UNHANDLED;
79 g_tls_interaction_default_ask_password_async (GTlsInteraction *interaction,
80 GTlsPassword *password,
81 GAsyncReadyCallback callback,
84 GSimpleAsyncResult *res;
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);
92 static GTlsInteractionResult
93 g_tls_interaction_default_ask_password_finish (GTlsInteraction *interaction,
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;
102 g_tls_interaction_init (GTlsInteraction *interaction)
107 g_tls_interaction_class_init (GTlsInteractionClass *klass)
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;
115 * g_tls_interaction_ask_password:
116 * @interaction: a #GTlsInteraction object
117 * @password: a #GTlsPassword object
119 * This function is normally called by #GTlsConnection or #GTlsDatabase to
120 * ask the user for a password.
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.
127 * Returns: The status of the ask password interaction.
131 GTlsInteractionResult
132 g_tls_interaction_ask_password (GTlsInteraction *interaction,
133 GTlsPassword *password)
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);
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
147 * This function is normally called by #GTlsConnection or #GTlsDatabase to
148 * ask the user for a password.
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.
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
163 g_tls_interaction_ask_password_async (GTlsInteraction *interaction,
164 GTlsPassword *password,
165 GAsyncReadyCallback callback,
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);
176 * g_tls_interaction_ask_password_finish:
177 * @interaction: a #GTlsInteraction object
178 * @result: the result passed to the callback
180 * Complete an ask password user interaction request. This should be once
181 * the g_tls_interaction_ask_password() completion callback is called.
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.
186 * Returns: The status of the ask password interaction.
190 GTlsInteractionResult
191 g_tls_interaction_ask_password_finish (GTlsInteraction *interaction,
192 GAsyncResult *result)
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);