docs/reference/gio/html/GAsyncResult.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>GAsyncResult</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="async.html" title="Asynchronous I/O">
   9 <link rel="prev" href="GCancellable.html" title="GCancellable">
  10 <link rel="next" href="gio-GIOScheduler.html" title="GIOScheduler">
  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="GCancellable.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="async.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="gio-GIOScheduler.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="#GAsyncResult.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#GAsyncResult.description" class="shortcut">Description</a>
  27                    |
  28                   <a href="#GAsyncResult.object-hierarchy" class="shortcut">Object Hierarchy</a>
  29                    |
  30                   <a href="#GAsyncResult.prerequisites" class="shortcut">Prerequisites</a>
  31                    |
  32                   <a href="#GAsyncResult.implementations" class="shortcut">Known Implementations</a>
  33 </td></tr>
  34 </table>
  35 <div class="refentry">
  36 <a name="GAsyncResult"></a><div class="titlepage"></div>
  37 <div class="refnamediv"><table width="100%"><tr>
  38 <td valign="top">
  39 <h2><span class="refentrytitle"><a name="GAsyncResult.top_of_page"></a>GAsyncResult</span></h2>
  40 <p>GAsyncResult — Asynchronous Function Results</p>
  41 </td>
  42 <td valign="top" align="right"></td>
  43 </tr></table></div>
  44 <div class="refsynopsisdiv">
  45 <a name="GAsyncResult.synopsis"></a><h2>Synopsis</h2>
  46 <pre class="synopsis">
  47 #include &lt;gio/gio.h&gt;
  48
  49                     <a class="link" href="GAsyncResult.html#GAsyncResult-struct" title="GAsyncResult">GAsyncResult</a>;
  50 struct              <a class="link" href="GAsyncResult.html#GAsyncResultIface" title="struct GAsyncResultIface">GAsyncResultIface</a>;
  51 <span class="returnvalue">void</span>                (<a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()">*GAsyncReadyCallback</a>)              (<em class="parameter"><code><a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> *source_object</code></em>,
  52                                                          <em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *res</code></em>,
  53                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  54 <a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="GAsyncResult.html#g-async-result-get-user-data" title="g_async_result_get_user_data ()">g_async_result_get_user_data</a>        (<em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *res</code></em>);
  55 <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject"><span class="returnvalue">GObject</span></a> *           <a class="link" href="GAsyncResult.html#g-async-result-get-source-object" title="g_async_result_get_source_object ()">g_async_result_get_source_object</a>    (<em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *res</code></em>);
  56 </pre>
  57 </div>
  58 <div class="refsect1">
  59 <a name="GAsyncResult.object-hierarchy"></a><h2>Object Hierarchy</h2>
  60 <pre class="synopsis">
  61   GInterface
  62    +----GAsyncResult
  63 </pre>
  64 </div>
  65 <div class="refsect1">
  66 <a name="GAsyncResult.prerequisites"></a><h2>Prerequisites</h2>
  67 <p>
  68 GAsyncResult requires
  69  <a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>.</p>
  70 </div>
  71 <div class="refsect1">
  72 <a name="GAsyncResult.implementations"></a><h2>Known Implementations</h2>
  73 <p>
  74 GAsyncResult is implemented by
  75  <a class="link" href="GSimpleAsyncResult.html" title="GSimpleAsyncResult">GSimpleAsyncResult</a>.</p>
  76 </div>
  77 <div class="refsect1">
  78 <a name="GAsyncResult.description"></a><h2>Description</h2>
  79 <p>
  80 Provides a base class for implementing asynchronous function results.
  81 </p>
  82 <p>
  83 Asynchronous operations are broken up into two separate operations
  84 which are chained together by a <a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a>. To begin
  85 an asynchronous operation, provide a <a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> to the
  86 asynchronous function. This callback will be triggered when the
  87 operation has completed, and will be passed a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> instance
  88 filled with the details of the operation's success or failure, the
  89 object the asynchronous function was started for and any error codes
  90 returned. The asynchronous callback function is then expected to call
  91 the corresponding "<code class="function">_finish()</code>" function, passing the object the
  92 function was called for, the <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> instance, and (optionally)
  93 an <em class="parameter"><code>error</code></em> to grab any error conditions that may have occurred.
  94 </p>
  95 <p>
  96 The "<code class="function">_finish()</code>" function for an operation takes the generic result
  97 (of type <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>) and returns the specific result that the
  98 operation in question yields (e.g. a <a class="link" href="GFileEnumerator.html" title="GFileEnumerator"><span class="type">GFileEnumerator</span></a> for a
  99 "enumerate children" operation). If the result or error status of the
 100 operation is not needed, there is no need to call the "<code class="function">_finish()</code>"
 101 function; GIO will take care of cleaning up the result and error
 102 information after the <a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> returns. You can pass
 103 <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> for the <a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> if you don't need to take any
 104 action at all after the operation completes. Applications may also
 105 take a reference to the <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> and call "<code class="function">_finish()</code>" later;
 106 however, the "<code class="function">_finish()</code>" function may be called at most once.
 107 </p>
 108 <p>
 109 Example of a typical asynchronous operation flow:
 110 </p>
 111 <div class="informalexample">
 112   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 113     <tbody>
 114       <tr>
 115         <td class="listing_lines" align="right"><pre>1
 116 2
 117 3
 118 4
 119 5
 120 6
 121 7
 122 8
 123 9
 124 10
 125 11
 126 12
 127 13
 128 14
 129 15
 130 16
 131 17
 132 18
 133 19
 134 20
 135 21
 136 22
 137 23
 138 24
 139 25
 140 26
 141 27
 142 28
 143 29
 144 30
 145 31
 146 32
 147 33
 148 34
 149 35
 150 36
 151 37
 152 38</pre></td>
 153         <td class="listing_code"><pre class="programlisting"><span class="type">void</span><span class="normal"> </span><span class="function">_theoretical_frobnitz_async</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Theoretical</span><span class="normal">         </span><span class="symbol">*</span><span class="normal">t</span><span class="symbol">,</span>
 154 <span class="normal">                                  </span><span class="usertype">GCancellable</span><span class="normal">        </span><span class="symbol">*</span><span class="normal">c</span><span class="symbol">,</span>
 155 <span class="normal">                                  </span><span class="usertype">GAsyncReadyCallback</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cb</span><span class="symbol">,</span>
 156 <span class="normal">                                  </span><span class="usertype">gpointer</span><span class="normal">             u</span><span class="symbol">);</span>
 157
 158 <span class="normal"><a href="./../glib/glib/glib-Basic-Types.html#gboolean">gboolean</a> </span><span class="function">_theoretical_frobnitz_finish</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Theoretical</span><span class="normal">   </span><span class="symbol">*</span><span class="normal">t</span><span class="symbol">,</span>
 159 <span class="normal">                                       </span><span class="usertype">GAsyncResult</span><span class="normal">  </span><span class="symbol">*</span><span class="normal">res</span><span class="symbol">,</span>
 160 <span class="normal">                                       </span><span class="usertype">GError</span><span class="normal">       </span><span class="symbol">**</span><span class="normal">e</span><span class="symbol">);</span>
 161
 162 <span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
 163 <span class="function">frobnitz_result_func</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GObject</span><span class="normal">      </span><span class="symbol">*</span><span class="normal">source_object</span><span class="symbol">,</span>
 164 <span class="normal">         </span><span class="usertype">GAsyncResult</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">res</span><span class="symbol">,</span>
 165 <span class="normal">         </span><span class="usertype">gpointer</span><span class="normal">      user_data</span><span class="symbol">)</span>
 166 <span class="cbracket">{</span>
 167 <span class="normal">  </span><span class="usertype">gboolean</span><span class="normal"> success </span><span class="symbol">=</span><span class="normal"> <a href="./../glib/glib/glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">;</span>
 168
 169 <span class="normal">  success </span><span class="symbol">=</span><span class="normal"> </span><span class="function">_theoretical_frobnitz_finish</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">source_object</span><span class="symbol">,</span><span class="normal"> res</span><span class="symbol">,</span><span class="normal"> <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
 170
 171 <span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">success</span><span class="symbol">)</span>
 172 <span class="normal">    </span><span class="function"><a href="./../glib/glib/glib-String-Utility-Functions.html#g-printf">g_printf</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"Hurray!</span><span class="specialchar">\n</span><span class="string">"</span><span class="symbol">);</span>
 173 <span class="normal">  </span><span class="keyword">else</span>
 174 <span class="normal">    </span><span class="function"><a href="./../glib/glib/glib-String-Utility-Functions.html#g-printf">g_printf</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"Uh oh!</span><span class="specialchar">\n</span><span class="string">"</span><span class="symbol">);</span>
 175
 176 <span class="normal">  </span><span class="comment">/* ... */</span>
 177
 178 <span class="cbracket">}</span>
 179
 180 <span class="type">int</span><span class="normal"> </span><span class="function">main</span><span class="normal"> </span><span class="symbol">(</span><span class="type">int</span><span class="normal"> argc</span><span class="symbol">,</span><span class="normal"> </span><span class="type">void</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">argv</span><span class="symbol">[])</span>
 181 <span class="cbracket">{</span>
 182 <span class="normal">   </span><span class="comment">/* ... */</span>
 183
 184 <span class="normal">   </span><span class="function">_theoretical_frobnitz_async</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">theoretical_data</span><span class="symbol">,</span>
 185 <span class="normal">                                <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">,</span>
 186 <span class="normal">                                frobnitz_result_func</span><span class="symbol">,</span>
 187 <span class="normal">                                <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>
 188
 189 <span class="normal">   </span><span class="comment">/* ... */</span>
 190 <span class="cbracket">}</span></pre></td>
 191       </tr>
 192     </tbody>
 193   </table>
 194 </div>
 195
 196 <p>
 197 </p>
 198 <p>
 199 The callback for an asynchronous operation is called only once, and is
 200 always called, even in the case of a cancelled operation. On cancellation
 201 the result is a <a class="link" href="gio-GIOError.html#G-IO-ERROR-CANCELLED:CAPS"><code class="literal">G_IO_ERROR_CANCELLED</code></a> error.
 202 </p>
 203 </div>
 204 <div class="refsect1">
 205 <a name="GAsyncResult.details"></a><h2>Details</h2>
 206 <div class="refsect2">
 207 <a name="GAsyncResult-struct"></a><h3>GAsyncResult</h3>
 208 <pre class="programlisting">typedef struct _GAsyncResult GAsyncResult;</pre>
 209 <p>
 210 Holds results information for an asynchronous operation,
 211 usually passed directly to a asynchronous <code class="function">_finish()</code> operation.
 212 </p>
 213 </div>
 214 <hr>
 215 <div class="refsect2">
 216 <a name="GAsyncResultIface"></a><h3>struct GAsyncResultIface</h3>
 217 <pre class="programlisting">struct GAsyncResultIface {
 218   GTypeInterface g_iface;
 219
 220   /* Virtual Table */
 221
 222   gpointer  (* get_user_data)     (GAsyncResult *res);
 223   GObject * (* get_source_object) (GAsyncResult *res);
 224 };
 225 </pre>
 226 <p>
 227 Interface definition for <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>.
 228 </p>
 229 <div class="variablelist"><table border="0">
 230 <col align="left" valign="top">
 231 <tbody>
 232 <tr>
 233 <td><p><span class="term"><a href="./../gobject/gobject/gobject-Type-Information.html#GTypeInterface"><span class="type">GTypeInterface</span></a> <em class="structfield"><code><a name="GAsyncResultIface.g-iface"></a>g_iface</code></em>;</span></p></td>
 234 <td>The parent interface.</td>
 235 </tr>
 236 <tr>
 237 <td><p><span class="term"><em class="structfield"><code><a name="GAsyncResultIface.get-user-data"></a>get_user_data</code></em> ()</span></p></td>
 238 <td>Gets the user data passed to the callback.</td>
 239 </tr>
 240 <tr>
 241 <td><p><span class="term"><em class="structfield"><code><a name="GAsyncResultIface.get-source-object"></a>get_source_object</code></em> ()</span></p></td>
 242 <td>Gets the source object that issued the asynchronous operation.</td>
 243 </tr>
 244 </tbody>
 245 </table></div>
 246 </div>
 247 <hr>
 248 <div class="refsect2">
 249 <a name="GAsyncReadyCallback"></a><h3>GAsyncReadyCallback ()</h3>
 250 <pre class="programlisting"><span class="returnvalue">void</span>                (*GAsyncReadyCallback)              (<em class="parameter"><code><a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> *source_object</code></em>,
 251                                                          <em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *res</code></em>,
 252                                                          <em class="parameter"><code><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 253 <p>
 254 Type definition for a function that will be called back when an asynchronous
 255 operation within GIO has been completed.
 256 </p>
 257 <div class="variablelist"><table border="0">
 258 <col align="left" valign="top">
 259 <tbody>
 260 <tr>
 261 <td><p><span class="term"><em class="parameter"><code>source_object</code></em> :</span></p></td>
 262 <td>the object the asynchronous operation was started with.</td>
 263 </tr>
 264 <tr>
 265 <td><p><span class="term"><em class="parameter"><code>res</code></em> :</span></p></td>
 266 <td>a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>.</td>
 267 </tr>
 268 <tr>
 269 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 270 <td>user data passed to the callback.</td>
 271 </tr>
 272 </tbody>
 273 </table></div>
 274 </div>
 275 <hr>
 276 <div class="refsect2">
 277 <a name="g-async-result-get-user-data"></a><h3>g_async_result_get_user_data ()</h3>
 278 <pre class="programlisting"><a href="./../glib/glib/glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a>            g_async_result_get_user_data        (<em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *res</code></em>);</pre>
 279 <p>
 280 Gets the user data from a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>.
 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>res</code></em> :</span></p></td>
 287 <td>a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>.</td>
 288 </tr>
 289 <tr>
 290 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 291 <td>the user data for <em class="parameter"><code>res</code></em>. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 292 </td>
 293 </tr>
 294 </tbody>
 295 </table></div>
 296 </div>
 297 <hr>
 298 <div class="refsect2">
 299 <a name="g-async-result-get-source-object"></a><h3>g_async_result_get_source_object ()</h3>
 300 <pre class="programlisting"><a href="./../gobject/gobject/gobject-The-Base-Object-Type.html#GObject"><span class="returnvalue">GObject</span></a> *           g_async_result_get_source_object    (<em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *res</code></em>);</pre>
 301 <p>
 302 Gets the source object from a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>.
 303 </p>
 304 <div class="variablelist"><table border="0">
 305 <col align="left" valign="top">
 306 <tbody>
 307 <tr>
 308 <td><p><span class="term"><em class="parameter"><code>res</code></em> :</span></p></td>
 309 <td>a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>
 310 </td>
 311 </tr>
 312 <tr>
 313 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 314 <td>a new reference to the source object for the <em class="parameter"><code>res</code></em>,
 315 or <a href="./../glib/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if there is none. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
 316 </td>
 317 </tr>
 318 </tbody>
 319 </table></div>
 320 </div>
 321 </div>
 322 <div class="refsect1">
 323 <a name="GAsyncResult.see-also"></a><h2>See Also</h2>
 324 <a class="link" href="GSimpleAsyncResult.html" title="GSimpleAsyncResult"><span class="type">GSimpleAsyncResult</span></a>
 325 </div>
 326 </div>
 327 <div class="footer">
 328 <hr>
 329           Generated by GTK-Doc V1.18</div>
 330 </body>
 331 </html>