<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-01E7AE98-024C-4119-87D0-5BB9D53DA119" xml:lang="en"><title>Introduction
to <codeph>libgmodule</codeph></title><shortdesc><codeph>libgmodule</codeph> has APIs that provide a portable method
for dynamically loading 'plug-ins' or, in other words, DLLs. Any program that
wants to dynamically load modules must be linked to <codeph>libgmodule</codeph>.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>In order to use the <codeph>libgmodule</codeph> APIs, the user must check
whether dynamic loading of DLLs is supported by the platform by using the <codeph>g_module_supported()</codeph> API
which returns TRUE if the dynamic loading of modules is supported. P.I.P.S.
provides the implementation of <codeph>libdl</codeph>, where dynamic loading
of modules is supported, but to write code which runs across platforms the
user must do a check before using the <codeph>libgmodule</codeph> APIs.  </p>
<p>If the dynamic loading of DLLs is supported, use <codeph>g_module_open()</codeph> to
open the module. It takes the name of the module as the first argument and
the flags as the second argument.</p>
<note><codeph>G_MODULE_BIND_LOCAL</codeph> is the only flag currently supported.
The other flags are not supported. If the user specifies any other flag, the
module is loaded using the flag <codeph>G_MODULE_BIND_LOCAL</codeph> and not
by the user-specified flag.</note>
<p><b><codeph>GModule * g_module_open(const gchar *file_name, GModuleFlags
flags);</codeph></b></p>
<ul>
<li><p><b><codeph>file_name</codeph>:</b> The name of the file containing
the module.</p></li>
<li><p><b><codeph>flags</codeph>:</b> The flags used for opening the module. </p></li>
</ul>
<p>Once the module is opened, the user can find the module symbols (for example,.
function names) using the function </p>
<p><codeph>g_module_symbol()</codeph>.</p>
<p><b><codeph>gboolean g_module_symbol (GModule *module, const gchar *symbol_name,
gpointer *symbol);</codeph></b></p>
<ul>
<li><p><b><codeph>*module</codeph>:</b> This is a pointer returned when a
module is opened using <codeph>g_module_open()</codeph>.</p></li>
<li><p><b><codeph>symbol_name</codeph>:</b> This is the ordinal number of
the symbol that one wants to open. There is a difference between Symbian GLib
and OSS GLib; as in Linux the <codeph>symbol_name</codeph> is the name of
the symbol and not a number. The ordinal number must be passed as a string
and not a number.</p></li>
<li><p><b><codeph>symbol</codeph>:</b> This is the pointer to the symbol value </p></li>
</ul>
<p>The <codeph>GModule</codeph> can be closed by using the <codeph>g_module_close()</codeph> API.
This API returns TRUE if it successfully closed the module; else it returns
FALSE.</p>
<p><b><codeph>gboolean g_module_close(GModule *module);</codeph></b></p>
<ul>
<li><p><b><codeph>*module</codeph></b> The <codeph>GModule</codeph> to close. </p></li>
</ul>
<p>The following example code explains the usage of the <codeph>libgmodule</codeph> APIs.
It opens a module <filepath>libmoduletestplugin_a.dll</filepath> and uses
its <codeph>gplugin_a_func1()</codeph> API which is ordinal number 1. Finally,
the module is closed.</p>
<codeblock xml:space="preserve">#include &lt;gmodule.h&gt;
#include &lt;glib.h&gt;
typedef int (*SimpleFunc) (void);

int main()
{
  GModule *module = NULL;
  gpointer func;
  SimpleFunc f_a;
  int retVal;
  
  if (!g_module_supported())
  {
        g_print ("Dynamic Opening of modules is not supported");
        return 1;
  }
  
  /* G_MODULE_BIND_LAZY is overridden and the module is opened with
   * flag G_MODULE_BIND_LOCAL
   */
  module = g_module_open("libmoduletestplugin_a.dll",G_MODULE_BIND_LAZY);
  
  // 1 is the ordinal number for gplugin_a_func1
  if(module &amp;&amp; g_module_symbol(module, "1" ,&amp;func)) 	
  {
        f_a = (SimpleFunc)func;
        retVal = f_a();	
        g_print("Function at ordinal number 1 of module libgmodule_a returns %d",retVal);
  }
  else
  {
        g_print("Error quering symbol at ordinal number 1");
        return 1;
  }
  
  return 0;
}</codeblock>
<p>See the <b>Libgmodule APIs</b> section in <xref href="GUID-4ADD8234-4AFD-4E80-94A4-AC018FE83276.dita">Differences
between OSS and Symbian GLib</xref> for more details about <codeph>libgmodule</codeph> limitations
in the Symbian GLib implementation.  </p>
</conbody></concept>