docs/reference/gio/html/GTlsInteraction.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>GTlsInteraction</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GIO Reference Manual">
   8 <link rel="up" href="tls.html" title="TLS (SSL) support">
   9 <link rel="prev" href="GTlsFileDatabase.html" title="GTlsFileDatabase">
  10 <link rel="next" href="GTlsPassword.html" title="GTlsPassword">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="GTlsFileDatabase.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="tls.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GIO Reference Manual</th>
  21 <td><a accesskey="n" href="GTlsPassword.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#GTlsInteraction.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#GTlsInteraction.description" class="shortcut">Description</a>
  27                    |
  28                   <a href="#GTlsInteraction.object-hierarchy" class="shortcut">Object Hierarchy</a>
  29 </td></tr>
  30 </table>
  31 <div class="refentry">
  32 <a name="GTlsInteraction"></a><div class="titlepage"></div>
  33 <div class="refnamediv"><table width="100%"><tr>
  34 <td valign="top">
  35 <h2><span class="refentrytitle"><a name="GTlsInteraction.top_of_page"></a>GTlsInteraction</span></h2>
  36 <p>GTlsInteraction — Interaction with the user during TLS operations.</p>
  37 </td>
  38 <td valign="top" align="right"></td>
  39 </tr></table></div>
  40 <div class="refsynopsisdiv">
  41 <a name="GTlsInteraction.synopsis"></a><h2>Synopsis</h2>
  42 <pre class="synopsis">
  43 #include &lt;gio/gio.h&gt;
  44
  45                     <a class="link" href="GTlsInteraction.html#GTlsInteraction-struct" title="GTlsInteraction">GTlsInteraction</a>;
  46 enum                <a class="link" href="GTlsInteraction.html#GTlsInteractionResult" title="enum GTlsInteractionResult">GTlsInteractionResult</a>;
  47 <a class="link" href="GTlsInteraction.html#GTlsInteractionResult" title="enum GTlsInteractionResult"><span class="returnvalue">GTlsInteractionResult</span></a> <a class="link" href="GTlsInteraction.html#g-tls-interaction-ask-password" title="g_tls_interaction_ask_password ()">g_tls_interaction_ask_password</a>    (<em class="parameter"><code><a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a> *interaction</code></em>,
  48                                                          <em class="parameter"><code><a class="link" href="GTlsPassword.html" title="GTlsPassword"><span class="type">GTlsPassword</span></a> *password</code></em>,
  49                                                          <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
  50                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);
  51 <span class="returnvalue">void</span>                <a class="link" href="GTlsInteraction.html#g-tls-interaction-ask-password-async" title="g_tls_interaction_ask_password_async ()">g_tls_interaction_ask_password_async</a>
  52                                                         (<em class="parameter"><code><a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a> *interaction</code></em>,
  53                                                          <em class="parameter"><code><a class="link" href="GTlsPassword.html" title="GTlsPassword"><span class="type">GTlsPassword</span></a> *password</code></em>,
  54                                                          <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
  55                                                          <em class="parameter"><code><a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> callback</code></em>,
  56                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  57 <a class="link" href="GTlsInteraction.html#GTlsInteractionResult" title="enum GTlsInteractionResult"><span class="returnvalue">GTlsInteractionResult</span></a> <a class="link" href="GTlsInteraction.html#g-tls-interaction-ask-password-finish" title="g_tls_interaction_ask_password_finish ()">g_tls_interaction_ask_password_finish</a>
  58                                                         (<em class="parameter"><code><a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a> *interaction</code></em>,
  59                                                          <em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *result</code></em>,
  60                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);
  61 <a class="link" href="GTlsInteraction.html#GTlsInteractionResult" title="enum GTlsInteractionResult"><span class="returnvalue">GTlsInteractionResult</span></a> <a class="link" href="GTlsInteraction.html#g-tls-interaction-invoke-ask-password" title="g_tls_interaction_invoke_ask_password ()">g_tls_interaction_invoke_ask_password</a>
  62                                                         (<em class="parameter"><code><a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a> *interaction</code></em>,
  63                                                          <em class="parameter"><code><a class="link" href="GTlsPassword.html" title="GTlsPassword"><span class="type">GTlsPassword</span></a> *password</code></em>,
  64                                                          <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
  65                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);
  66 </pre>
  67 </div>
  68 <div class="refsect1">
  69 <a name="GTlsInteraction.object-hierarchy"></a><h2>Object Hierarchy</h2>
  70 <pre class="synopsis">
  71   <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>
  72    +----GTlsInteraction
  73 </pre>
  74 </div>
  75 <div class="refsect1">
  76 <a name="GTlsInteraction.description"></a><h2>Description</h2>
  77 <p>
  78 <a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a> provides a mechanism for the TLS connection and database
  79 code to interact with the user. It can be used to ask the user for passwords.
  80 </p>
  81 <p>
  82 To use a <a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a> with a TLS connection use
  83 <a class="link" href="GTlsConnection.html#g-tls-connection-set-interaction" title="g_tls_connection_set_interaction ()"><code class="function">g_tls_connection_set_interaction()</code></a>.
  84 </p>
  85 <p>
  86 Callers should instantiate a derived class that implements the various
  87 interaction methods to show the required dialogs.
  88 </p>
  89 <p>
  90 Callers should use the 'invoke' functions like
  91 <a class="link" href="GTlsInteraction.html#g-tls-interaction-invoke-ask-password" title="g_tls_interaction_invoke_ask_password ()"><code class="function">g_tls_interaction_invoke_ask_password()</code></a> to run interaction methods. These
  92 functions make sure that the interaction is invoked in the main loop
  93 and not in the current thread, if the current thread is not running the
  94 main loop.
  95 </p>
  96 <p>
  97 Derived classes can choose to implement whichever interactions methods they'd
  98 like to support by overriding those virtual methods in their class
  99 initialization function. Any interactions not implemented will return
 100 <a class="link" href="GTlsInteraction.html#G-TLS-INTERACTION-UNHANDLED:CAPS"><code class="literal">G_TLS_INTERACTION_UNHANDLED</code></a>. If a derived class implements an async method,
 101 it must also implement the corresponding finish method.
 102 </p>
 103 </div>
 104 <div class="refsect1">
 105 <a name="GTlsInteraction.details"></a><h2>Details</h2>
 106 <div class="refsect2">
 107 <a name="GTlsInteraction-struct"></a><h3>GTlsInteraction</h3>
 108 <pre class="programlisting">typedef struct _GTlsInteraction GTlsInteraction;</pre>
 109 <p>
 110 An object representing interaction that the TLS connection and database
 111 might have with the user.
 112 </p>
 113 <p class="since">Since 2.30</p>
 114 </div>
 115 <hr>
 116 <div class="refsect2">
 117 <a name="GTlsInteractionResult"></a><h3>enum GTlsInteractionResult</h3>
 118 <pre class="programlisting">typedef enum {
 119   G_TLS_INTERACTION_UNHANDLED,
 120   G_TLS_INTERACTION_HANDLED,
 121   G_TLS_INTERACTION_FAILED
 122 } GTlsInteractionResult;
 123 </pre>
 124 <p>
 125 <a class="link" href="GTlsInteraction.html#GTlsInteractionResult" title="enum GTlsInteractionResult"><span class="type">GTlsInteractionResult</span></a> is returned by various functions in <a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a>
 126 when finishing an interaction request.
 127 </p>
 128 <div class="variablelist"><table border="0">
 129 <col align="left" valign="top">
 130 <tbody>
 131 <tr>
 132 <td><p><a name="G-TLS-INTERACTION-UNHANDLED:CAPS"></a><span class="term"><code class="literal">G_TLS_INTERACTION_UNHANDLED</code></span></p></td>
 133 <td>The interaction was unhandled (i.e. not
 134     implemented).
 135 </td>
 136 </tr>
 137 <tr>
 138 <td><p><a name="G-TLS-INTERACTION-HANDLED:CAPS"></a><span class="term"><code class="literal">G_TLS_INTERACTION_HANDLED</code></span></p></td>
 139 <td>The interaction completed, and resulting data
 140     is available.
 141 </td>
 142 </tr>
 143 <tr>
 144 <td><p><a name="G-TLS-INTERACTION-FAILED:CAPS"></a><span class="term"><code class="literal">G_TLS_INTERACTION_FAILED</code></span></p></td>
 145 <td>The interaction has failed, or was cancelled.
 146     and the operation should be aborted.
 147 </td>
 148 </tr>
 149 </tbody>
 150 </table></div>
 151 <p class="since">Since 2.30</p>
 152 </div>
 153 <hr>
 154 <div class="refsect2">
 155 <a name="g-tls-interaction-ask-password"></a><h3>g_tls_interaction_ask_password ()</h3>
 156 <pre class="programlisting"><a class="link" href="GTlsInteraction.html#GTlsInteractionResult" title="enum GTlsInteractionResult"><span class="returnvalue">GTlsInteractionResult</span></a> g_tls_interaction_ask_password    (<em class="parameter"><code><a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a> *interaction</code></em>,
 157                                                          <em class="parameter"><code><a class="link" href="GTlsPassword.html" title="GTlsPassword"><span class="type">GTlsPassword</span></a> *password</code></em>,
 158                                                          <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
 159                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 160 <p>
 161 Run synchronous interaction to ask the user for a password. In general,
 162 <a class="link" href="GTlsInteraction.html#g-tls-interaction-invoke-ask-password" title="g_tls_interaction_invoke_ask_password ()"><code class="function">g_tls_interaction_invoke_ask_password()</code></a> should be used instead of this
 163 function.
 164 </p>
 165 <p>
 166 Derived subclasses usually implement a password prompt, although they may
 167 also choose to provide a password from elsewhere. The <em class="parameter"><code>password</code></em> value will
 168 be filled in and then <em class="parameter"><code>callback</code></em> will be called. Alternatively the user may
 169 abort this password request, which will usually abort the TLS connection.
 170 </p>
 171 <p>
 172 If the interaction is cancelled by the cancellation object, or by the
 173 user then <a class="link" href="GTlsInteraction.html#G-TLS-INTERACTION-FAILED:CAPS"><code class="literal">G_TLS_INTERACTION_FAILED</code></a> will be returned with an error that
 174 contains a <a class="link" href="gio-GIOError.html#G-IO-ERROR-CANCELLED:CAPS"><code class="literal">G_IO_ERROR_CANCELLED</code></a> error code. Certain implementations may
 175 not support immediate cancellation.
 176 </p>
 177 <div class="variablelist"><table border="0">
 178 <col align="left" valign="top">
 179 <tbody>
 180 <tr>
 181 <td><p><span class="term"><em class="parameter"><code>interaction</code></em> :</span></p></td>
 182 <td>a <a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a> object</td>
 183 </tr>
 184 <tr>
 185 <td><p><span class="term"><em class="parameter"><code>password</code></em> :</span></p></td>
 186 <td>a <a class="link" href="GTlsPassword.html" title="GTlsPassword"><span class="type">GTlsPassword</span></a> object</td>
 187 </tr>
 188 <tr>
 189 <td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
 190 <td>an optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> cancellation object</td>
 191 </tr>
 192 <tr>
 193 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 194 <td>an optional location to place an error on failure</td>
 195 </tr>
 196 <tr>
 197 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 198 <td>The status of the ask password interaction.</td>
 199 </tr>
 200 </tbody>
 201 </table></div>
 202 <p class="since">Since 2.30</p>
 203 </div>
 204 <hr>
 205 <div class="refsect2">
 206 <a name="g-tls-interaction-ask-password-async"></a><h3>g_tls_interaction_ask_password_async ()</h3>
 207 <pre class="programlisting"><span class="returnvalue">void</span>                g_tls_interaction_ask_password_async
 208                                                         (<em class="parameter"><code><a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a> *interaction</code></em>,
 209                                                          <em class="parameter"><code><a class="link" href="GTlsPassword.html" title="GTlsPassword"><span class="type">GTlsPassword</span></a> *password</code></em>,
 210                                                          <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
 211                                                          <em class="parameter"><code><a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> callback</code></em>,
 212                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 213 <p>
 214 Run asynchronous interaction to ask the user for a password. In general,
 215 <a class="link" href="GTlsInteraction.html#g-tls-interaction-invoke-ask-password" title="g_tls_interaction_invoke_ask_password ()"><code class="function">g_tls_interaction_invoke_ask_password()</code></a> should be used instead of this
 216 function.
 217 </p>
 218 <p>
 219 Derived subclasses usually implement a password prompt, although they may
 220 also choose to provide a password from elsewhere. The <em class="parameter"><code>password</code></em> value will
 221 be filled in and then <em class="parameter"><code>callback</code></em> will be called. Alternatively the user may
 222 abort this password request, which will usually abort the TLS connection.
 223 </p>
 224 <p>
 225 If the interaction is cancelled by the cancellation object, or by the
 226 user then <a class="link" href="GTlsInteraction.html#G-TLS-INTERACTION-FAILED:CAPS"><code class="literal">G_TLS_INTERACTION_FAILED</code></a> will be returned with an error that
 227 contains a <a class="link" href="gio-GIOError.html#G-IO-ERROR-CANCELLED:CAPS"><code class="literal">G_IO_ERROR_CANCELLED</code></a> error code. Certain implementations may
 228 not support immediate cancellation.
 229 </p>
 230 <p>
 231 Certain implementations may not support immediate cancellation.
 232 </p>
 233 <div class="variablelist"><table border="0">
 234 <col align="left" valign="top">
 235 <tbody>
 236 <tr>
 237 <td><p><span class="term"><em class="parameter"><code>interaction</code></em> :</span></p></td>
 238 <td>a <a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a> object</td>
 239 </tr>
 240 <tr>
 241 <td><p><span class="term"><em class="parameter"><code>password</code></em> :</span></p></td>
 242 <td>a <a class="link" href="GTlsPassword.html" title="GTlsPassword"><span class="type">GTlsPassword</span></a> object</td>
 243 </tr>
 244 <tr>
 245 <td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
 246 <td>an optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> cancellation object</td>
 247 </tr>
 248 <tr>
 249 <td><p><span class="term"><em class="parameter"><code>callback</code></em> :</span></p></td>
 250 <td>will be called when the interaction completes. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 251 </td>
 252 </tr>
 253 <tr>
 254 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 255 <td>data to pass to the <em class="parameter"><code>callback</code></em>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
 256 </td>
 257 </tr>
 258 </tbody>
 259 </table></div>
 260 <p class="since">Since 2.30</p>
 261 </div>
 262 <hr>
 263 <div class="refsect2">
 264 <a name="g-tls-interaction-ask-password-finish"></a><h3>g_tls_interaction_ask_password_finish ()</h3>
 265 <pre class="programlisting"><a class="link" href="GTlsInteraction.html#GTlsInteractionResult" title="enum GTlsInteractionResult"><span class="returnvalue">GTlsInteractionResult</span></a> g_tls_interaction_ask_password_finish
 266                                                         (<em class="parameter"><code><a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a> *interaction</code></em>,
 267                                                          <em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *result</code></em>,
 268                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 269 <p>
 270 Complete an ask password user interaction request. This should be once
 271 the <a class="link" href="GTlsInteraction.html#g-tls-interaction-ask-password-async" title="g_tls_interaction_ask_password_async ()"><code class="function">g_tls_interaction_ask_password_async()</code></a> completion callback is called.
 272 </p>
 273 <p>
 274 If <a class="link" href="GTlsInteraction.html#G-TLS-INTERACTION-HANDLED:CAPS"><code class="literal">G_TLS_INTERACTION_HANDLED</code></a> is returned, then the <a class="link" href="GTlsPassword.html" title="GTlsPassword"><span class="type">GTlsPassword</span></a> passed
 275 to <a class="link" href="GTlsInteraction.html#g-tls-interaction-ask-password" title="g_tls_interaction_ask_password ()"><code class="function">g_tls_interaction_ask_password()</code></a> will have its password filled in.
 276 </p>
 277 <p>
 278 If the interaction is cancelled by the cancellation object, or by the
 279 user then <a class="link" href="GTlsInteraction.html#G-TLS-INTERACTION-FAILED:CAPS"><code class="literal">G_TLS_INTERACTION_FAILED</code></a> will be returned with an error that
 280 contains a <a class="link" href="gio-GIOError.html#G-IO-ERROR-CANCELLED:CAPS"><code class="literal">G_IO_ERROR_CANCELLED</code></a> error code.
 281 </p>
 282 <div class="variablelist"><table border="0">
 283 <col align="left" valign="top">
 284 <tbody>
 285 <tr>
 286 <td><p><span class="term"><em class="parameter"><code>interaction</code></em> :</span></p></td>
 287 <td>a <a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a> object</td>
 288 </tr>
 289 <tr>
 290 <td><p><span class="term"><em class="parameter"><code>result</code></em> :</span></p></td>
 291 <td>the result passed to the callback</td>
 292 </tr>
 293 <tr>
 294 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 295 <td>an optional location to place an error on failure</td>
 296 </tr>
 297 <tr>
 298 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 299 <td>The status of the ask password interaction.</td>
 300 </tr>
 301 </tbody>
 302 </table></div>
 303 <p class="since">Since 2.30</p>
 304 </div>
 305 <hr>
 306 <div class="refsect2">
 307 <a name="g-tls-interaction-invoke-ask-password"></a><h3>g_tls_interaction_invoke_ask_password ()</h3>
 308 <pre class="programlisting"><a class="link" href="GTlsInteraction.html#GTlsInteractionResult" title="enum GTlsInteractionResult"><span class="returnvalue">GTlsInteractionResult</span></a> g_tls_interaction_invoke_ask_password
 309                                                         (<em class="parameter"><code><a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a> *interaction</code></em>,
 310                                                          <em class="parameter"><code><a class="link" href="GTlsPassword.html" title="GTlsPassword"><span class="type">GTlsPassword</span></a> *password</code></em>,
 311                                                          <em class="parameter"><code><a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> *cancellable</code></em>,
 312                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 313 <p>
 314 Invoke the interaction to ask the user for a password. It invokes this
 315 interaction in the main loop, specifically the <a href="./../glib/glib/glib-The-Main-Event-Loop.html#GMainContext"><span class="type">GMainContext</span></a> returned by
 316 <a href="./../glib/glib/glib-The-Main-Event-Loop.html#g-main-context-get-thread-default"><code class="function">g_main_context_get_thread_default()</code></a> when the interaction is created. This
 317 is called by called by <a class="link" href="GTlsConnection.html" title="GTlsConnection"><span class="type">GTlsConnection</span></a> or <a class="link" href="GTlsDatabase.html" title="GTlsDatabase"><span class="type">GTlsDatabase</span></a> to ask the user
 318 for a password.
 319 </p>
 320 <p>
 321 Derived subclasses usually implement a password prompt, although they may
 322 also choose to provide a password from elsewhere. The <em class="parameter"><code>password</code></em> value will
 323 be filled in and then <em class="parameter"><code>callback</code></em> will be called. Alternatively the user may
 324 abort this password request, which will usually abort the TLS connection.
 325 </p>
 326 <p>
 327 The implementation can either be a synchronous (eg: modal dialog) or an
 328 asynchronous one (eg: modeless dialog). This function will take care of
 329 calling which ever one correctly.
 330 </p>
 331 <p>
 332 If the interaction is cancelled by the cancellation object, or by the
 333 user then <a class="link" href="GTlsInteraction.html#G-TLS-INTERACTION-FAILED:CAPS"><code class="literal">G_TLS_INTERACTION_FAILED</code></a> will be returned with an error that
 334 contains a <a class="link" href="gio-GIOError.html#G-IO-ERROR-CANCELLED:CAPS"><code class="literal">G_IO_ERROR_CANCELLED</code></a> error code. Certain implementations may
 335 not support immediate cancellation.
 336 </p>
 337 <div class="variablelist"><table border="0">
 338 <col align="left" valign="top">
 339 <tbody>
 340 <tr>
 341 <td><p><span class="term"><em class="parameter"><code>interaction</code></em> :</span></p></td>
 342 <td>a <a class="link" href="GTlsInteraction.html" title="GTlsInteraction"><span class="type">GTlsInteraction</span></a> object</td>
 343 </tr>
 344 <tr>
 345 <td><p><span class="term"><em class="parameter"><code>password</code></em> :</span></p></td>
 346 <td>a <a class="link" href="GTlsPassword.html" title="GTlsPassword"><span class="type">GTlsPassword</span></a> object</td>
 347 </tr>
 348 <tr>
 349 <td><p><span class="term"><em class="parameter"><code>cancellable</code></em> :</span></p></td>
 350 <td>an optional <a class="link" href="GCancellable.html" title="GCancellable"><span class="type">GCancellable</span></a> cancellation object</td>
 351 </tr>
 352 <tr>
 353 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 354 <td>an optional location to place an error on failure</td>
 355 </tr>
 356 <tr>
 357 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 358 <td>The status of the ask password interaction.</td>
 359 </tr>
 360 </tbody>
 361 </table></div>
 362 <p class="since">Since 2.30</p>
 363 </div>
 364 </div>
 365 </div>
 366 <div class="footer">
 367 <hr>
 368           Generated by GTK-Doc V1.18</div>
 369 </body>
 370 </html>