docs/reference/gio/html/GIOModule.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>GIOModule</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="GIO Reference Manual">
   8 <link rel="up" href="extending.html" title="Extending GIO">
   9 <link rel="prev" href="GVfs.html" title="GVfs">
  10 <link rel="next" href="gio-Extension-Points.html" title="Extension Points">
  11 <meta name="generator" content="GTK-Doc V1.13 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 <link rel="part" href="pt01.html" title="Part I. GIO Overview">
  14 <link rel="chapter" href="ch01.html" title="Introduction">
  15 <link rel="chapter" href="ch02.html" title="Compiling GIO applications">
  16 <link rel="chapter" href="ch03.html" title="Running GIO applications">
  17 <link rel="chapter" href="extending-gio.html" title="Extending GIO">
  18 <link rel="part" href="pt02.html" title="Part II. API Reference">
  19 <link rel="chapter" href="file_ops.html" title="File Operations">
  20 <link rel="chapter" href="file_mon.html" title="File System Monitoring">
  21 <link rel="chapter" href="async.html" title="Asynchronous I/O">
  22 <link rel="chapter" href="conversion.html" title="Data conversion">
  23 <link rel="chapter" href="streaming.html" title="Streaming I/O">
  24 <link rel="chapter" href="types.html" title="File types and applications">
  25 <link rel="chapter" href="volume_mon.html" title="Volumes and Drives">
  26 <link rel="chapter" href="icons.html" title="Icons">
  27 <link rel="chapter" href="failable_initialization.html" title="Failable Initialization">
  28 <link rel="chapter" href="networking.html" title="Lowlevel platform-independent network support">
  29 <link rel="chapter" href="resolver.html" title="DNS resolution">
  30 <link rel="chapter" href="highlevel-socket.html" title="Highlevel network functionallity">
  31 <link rel="chapter" href="utils.html" title="Utilities">
  32 <link rel="chapter" href="extending.html" title="Extending GIO">
  33 <link rel="part" href="migrating.html" title="Part III. Migrating to GIO">
  34 <link rel="chapter" href="ch19.html" title="Migrating from POSIX to GIO">
  35 <link rel="chapter" href="ch20.html" title="Migrating from GnomeVFS to GIO">
  36 <link rel="chapter" href="gio-hierarchy.html" title="Object Hierarchy">
  37 <link rel="index" href="api-index-full.html" title="Index">
  38 <link rel="index" href="api-index-deprecated.html" title="Index of deprecated symbols">
  39 <link rel="index" href="api-index-2-18.html" title="Index of new symbols in 2.18">
  40 <link rel="index" href="api-index-2-20.html" title="Index of new symbols in 2.20">
  41 <link rel="index" href="api-index-2-22.html" title="Index of new symbols in 2.22">
  42 <link rel="index" href="api-index-2-24.html" title="Index of new symbols in 2.24">
  43 </head>
  44 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  45 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  46 <tr valign="middle">
  47 <td><a accesskey="p" href="GVfs.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  48 <td><a accesskey="u" href="extending.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  49 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  50 <th width="100%" align="center">GIO Reference Manual</th>
  51 <td><a accesskey="n" href="gio-Extension-Points.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  52 </tr>
  53 <tr><td colspan="5" class="shortcuts">
  54 <a href="#GIOModule.synopsis" class="shortcut">Top</a>
  55                    |
  56                   <a href="#GIOModule.description" class="shortcut">Description</a>
  57                    |
  58                   <a href="#GIOModule.object-hierarchy" class="shortcut">Object Hierarchy</a>
  59                    |
  60                   <a href="#GIOModule.implemented-interfaces" class="shortcut">Implemented Interfaces</a>
  61 </td></tr>
  62 </table>
  63 <div class="refentry" title="GIOModule">
  64 <a name="GIOModule"></a><div class="titlepage"></div>
  65 <div class="refnamediv"><table width="100%"><tr>
  66 <td valign="top">
  67 <h2><span class="refentrytitle"><a name="GIOModule.top_of_page"></a>GIOModule</span></h2>
  68 <p>GIOModule — Loadable GIO Modules</p>
  69 </td>
  70 <td valign="top" align="right"></td>
  71 </tr></table></div>
  72 <div class="refsynopsisdiv" title="Synopsis">
  73 <a name="GIOModule.synopsis"></a><h2>Synopsis</h2>
  74 <pre class="synopsis">
  75 #include &lt;gio/gio.h&gt;
  76
  77                     <a class="link" href="GIOModule.html#GIOModule-struct" title="GIOModule">GIOModule</a>;
  78 <a class="link" href="GIOModule.html" title="GIOModule"><span class="returnvalue">GIOModule</span></a> *         <a class="link" href="GIOModule.html#g-io-module-new" title="g_io_module_new ()">g_io_module_new</a>                     (const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="returnvalue">gchar</span></a> *filename);
  79 <a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#GList"><span class="returnvalue">GList</span></a> *             <a class="link" href="GIOModule.html#g-io-modules-load-all-in-directory" title="g_io_modules_load_all_in_directory ()">g_io_modules_load_all_in_directory</a>  (const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="returnvalue">gchar</span></a> *dirname);
  80 <span class="returnvalue">void</span>                <a class="link" href="GIOModule.html#g-io-modules-scan-all-in-directory" title="g_io_modules_scan_all_in_directory ()">g_io_modules_scan_all_in_directory</a>  (const <span class="returnvalue">char</span> *dirname);
  81 <span class="returnvalue">void</span>                <a class="link" href="GIOModule.html#g-io-module-load" title="g_io_module_load ()">g_io_module_load</a>                    (<a class="link" href="GIOModule.html" title="GIOModule"><span class="returnvalue">GIOModule</span></a> *module);
  82 <span class="returnvalue">void</span>                <a class="link" href="GIOModule.html#g-io-module-unload" title="g_io_module_unload ()">g_io_module_unload</a>                  (<a class="link" href="GIOModule.html" title="GIOModule"><span class="returnvalue">GIOModule</span></a> *module);
  83 <span class="returnvalue">char</span> **             <a class="link" href="GIOModule.html#g-io-module-query" title="g_io_module_query ()">g_io_module_query</a>                   (void);
  84 </pre>
  85 </div>
  86 <div class="refsect1" title="Object Hierarchy">
  87 <a name="GIOModule.object-hierarchy"></a><h2>Object Hierarchy</h2>
  88 <pre class="synopsis">
  89   <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a>
  90    +----<a href="http://library.gnome.org/devel/gobject/unstable/GTypeModule.html">GTypeModule</a>
  91          +----GIOModule
  92 </pre>
  93 </div>
  94 <div class="refsect1" title="Implemented Interfaces">
  95 <a name="GIOModule.implemented-interfaces"></a><h2>Implemented Interfaces</h2>
  96 <p>
  97 GIOModule implements
  98  <a href="http://library.gnome.org/devel/gobject/unstable/GTypePlugin.html">GTypePlugin</a>.</p>
  99 </div>
 100 <div class="refsect1" title="Description">
 101 <a name="GIOModule.description"></a><h2>Description</h2>
 102 <p>
 103 Provides an interface and default functions for loading and unloading
 104 modules. This is used internally to make GIO extensible, but can also
 105 be used by others to implement module loading.</p>
 106 </div>
 107 <div class="refsect1" title="Details">
 108 <a name="GIOModule.details"></a><h2>Details</h2>
 109 <div class="refsect2" title="GIOModule">
 110 <a name="GIOModule-struct"></a><h3>GIOModule</h3>
 111 <pre class="programlisting">typedef struct _GIOModule GIOModule;</pre>
 112 <p>
 113 Opaque module base class for extending GIO.</p>
 114 </div>
 115 <hr>
 116 <div class="refsect2" title="g_io_module_new ()">
 117 <a name="g-io-module-new"></a><h3>g_io_module_new ()</h3>
 118 <pre class="programlisting"><a class="link" href="GIOModule.html" title="GIOModule"><span class="returnvalue">GIOModule</span></a> *         g_io_module_new                     (const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="returnvalue">gchar</span></a> *filename);</pre>
 119 <p>
 120 Creates a new GIOModule that will load the specific
 121 shared library when in use.</p>
 122 <div class="variablelist"><table border="0">
 123 <col align="left" valign="top">
 124 <tbody>
 125 <tr>
 126 <td><p><span class="term"><em class="parameter"><code>filename</code></em> :</span></p></td>
 127 <td> filename of the shared library module.
 128 </td>
 129 </tr>
 130 <tr>
 131 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 132 <td> a <a class="link" href="GIOModule.html" title="GIOModule"><span class="type">GIOModule</span></a> from given <em class="parameter"><code>filename</code></em>,
 133 or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> on error.
 134 </td>
 135 </tr>
 136 </tbody>
 137 </table></div>
 138 </div>
 139 <hr>
 140 <div class="refsect2" title="g_io_modules_load_all_in_directory ()">
 141 <a name="g-io-modules-load-all-in-directory"></a><h3>g_io_modules_load_all_in_directory ()</h3>
 142 <pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#GList"><span class="returnvalue">GList</span></a> *             g_io_modules_load_all_in_directory  (const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="returnvalue">gchar</span></a> *dirname);</pre>
 143 <p>
 144 Loads all the modules in the specified directory.
 145 </p>
 146 <p>
 147 If don't require all modules to be initialized (and thus registering
 148 all gtypes) then you can use <a class="link" href="GIOModule.html#g-io-modules-scan-all-in-directory" title="g_io_modules_scan_all_in_directory ()"><code class="function">g_io_modules_scan_all_in_directory()</code></a>
 149 which allows delayed/lazy loading of modules.</p>
 150 <div class="variablelist"><table border="0">
 151 <col align="left" valign="top">
 152 <tbody>
 153 <tr>
 154 <td><p><span class="term"><em class="parameter"><code>dirname</code></em> :</span></p></td>
 155 <td> pathname for a directory containing modules to load.
 156 </td>
 157 </tr>
 158 <tr>
 159 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 160 <td> a list of <a href="GIOModule.html"><span class="type">GIOModules</span></a> loaded from the directory,
 161      All the modules are loaded into memory, if you want to
 162      unload them (enabling on-demand loading) you must call
 163      <a href="http://library.gnome.org/devel/gobject/unstable/GTypeModule.html#g-type-module-unuse"><code class="function">g_type_module_unuse()</code></a> on all the modules. Free the list
 164      with <a href="http://library.gnome.org/devel/glib/unstable/glib-Doubly-Linked-Lists.html#g-list-free"><code class="function">g_list_free()</code></a>.
 165 </td>
 166 </tr>
 167 </tbody>
 168 </table></div>
 169 </div>
 170 <hr>
 171 <div class="refsect2" title="g_io_modules_scan_all_in_directory ()">
 172 <a name="g-io-modules-scan-all-in-directory"></a><h3>g_io_modules_scan_all_in_directory ()</h3>
 173 <pre class="programlisting"><span class="returnvalue">void</span>                g_io_modules_scan_all_in_directory  (const <span class="returnvalue">char</span> *dirname);</pre>
 174 <p>
 175 Scans all the modules in the specified directory, ensuring that
 176 any extension point implemented by a module is registered.
 177 </p>
 178 <p>
 179 This may not actually load and initialize all the types in each
 180 module, some modules may be lazily loaded and initialized when
 181 an extension point it implementes is used with e.g.
 182 <a class="link" href="gio-Extension-Points.html#g-io-extension-point-get-extensions" title="g_io_extension_point_get_extensions ()"><code class="function">g_io_extension_point_get_extensions()</code></a> or
 183 <a class="link" href="gio-Extension-Points.html#g-io-extension-point-get-extension-by-name" title="g_io_extension_point_get_extension_by_name ()"><code class="function">g_io_extension_point_get_extension_by_name()</code></a>.
 184 </p>
 185 <p>
 186 If you need to guarantee that all types are loaded in all the modules,
 187 use <a class="link" href="GIOModule.html#g-io-modules-scan-all-in-directory" title="g_io_modules_scan_all_in_directory ()"><code class="function">g_io_modules_scan_all_in_directory()</code></a>.</p>
 188 <div class="variablelist"><table border="0">
 189 <col align="left" valign="top">
 190 <tbody><tr>
 191 <td><p><span class="term"><em class="parameter"><code>dirname</code></em> :</span></p></td>
 192 <td> pathname for a directory containing modules to scan.
 193 </td>
 194 </tr></tbody>
 195 </table></div>
 196 <p class="since">Since 2.24</p>
 197 </div>
 198 <hr>
 199 <div class="refsect2" title="g_io_module_load ()">
 200 <a name="g-io-module-load"></a><h3>g_io_module_load ()</h3>
 201 <pre class="programlisting"><span class="returnvalue">void</span>                g_io_module_load                    (<a class="link" href="GIOModule.html" title="GIOModule"><span class="returnvalue">GIOModule</span></a> *module);</pre>
 202 <p>
 203 Required API for GIO modules to implement.
 204 This function is ran after the module has been loaded into GIO,
 205 to initialize the module.</p>
 206 <div class="variablelist"><table border="0">
 207 <col align="left" valign="top">
 208 <tbody><tr>
 209 <td><p><span class="term"><em class="parameter"><code>module</code></em> :</span></p></td>
 210 <td> a <a class="link" href="GIOModule.html" title="GIOModule"><span class="type">GIOModule</span></a>.
 211 </td>
 212 </tr></tbody>
 213 </table></div>
 214 </div>
 215 <hr>
 216 <div class="refsect2" title="g_io_module_unload ()">
 217 <a name="g-io-module-unload"></a><h3>g_io_module_unload ()</h3>
 218 <pre class="programlisting"><span class="returnvalue">void</span>                g_io_module_unload                  (<a class="link" href="GIOModule.html" title="GIOModule"><span class="returnvalue">GIOModule</span></a> *module);</pre>
 219 <p>
 220 Required API for GIO modules to implement.
 221 This function is ran when the module is being unloaded from GIO,
 222 to finalize the module.</p>
 223 <div class="variablelist"><table border="0">
 224 <col align="left" valign="top">
 225 <tbody><tr>
 226 <td><p><span class="term"><em class="parameter"><code>module</code></em> :</span></p></td>
 227 <td> a <a class="link" href="GIOModule.html" title="GIOModule"><span class="type">GIOModule</span></a>.
 228 </td>
 229 </tr></tbody>
 230 </table></div>
 231 </div>
 232 <hr>
 233 <div class="refsect2" title="g_io_module_query ()">
 234 <a name="g-io-module-query"></a><h3>g_io_module_query ()</h3>
 235 <pre class="programlisting"><span class="returnvalue">char</span> **             g_io_module_query                   (void);</pre>
 236 <p>
 237 Optional API for GIO modules to implement.
 238 </p>
 239 <p>
 240 Should return a list of all the extension points that may be
 241 implemented in this module.
 242 </p>
 243 <p>
 244 This method will not be called in normal use, however it may be
 245 called when probing existing modules and recording which extension
 246 points that this modle is used for. This means we won't have to
 247 load and initialze this module unless its needed.
 248 </p>
 249 <p>
 250 If this function is not implemented by the module the module will
 251 always be loaded, initialized and then unloaded on application startup
 252 so that it can register its extension points during init.
 253 </p>
 254 <p>
 255 Note that a module need not actually implement all the extension points
 256 that g_io_module_query returns, since the exact list of extension may
 257 depend on runtime issues. However all extension points actually implemented
 258 must be returned by <a class="link" href="GIOModule.html#g-io-module-query" title="g_io_module_query ()"><code class="function">g_io_module_query()</code></a> (if defined).
 259 </p>
 260 <p>
 261 When installing a module that implements g_io_module_query you must
 262 run gio-querymodules in order to build the cache files required for
 263 lazy loading.</p>
 264 <div class="variablelist"><table border="0">
 265 <col align="left" valign="top">
 266 <tbody><tr>
 267 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 268 <td> A <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>-terminated array of strings, listing the supported
 269     extension points of the module. The array must be suitable for
 270     freeing with <a href="http://library.gnome.org/devel/glib/unstable/glib-String-Utility-Functions.html#g-strfreev"><code class="function">g_strfreev()</code></a>.
 271
 272 </td>
 273 </tr></tbody>
 274 </table></div>
 275 <p class="since">Since 2.24</p>
 276 </div>
 277 </div>
 278 </div>
 279 <div class="footer">
 280 <hr>
 281           Generated by GTK-Doc V1.13</div>
 282 </body>
 283 </html>