|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-01E7AE98-024C-4119-87D0-5BB9D53DA119" xml:lang="en"><title>Introduction |
|
13 to <codeph>libgmodule</codeph></title><shortdesc><codeph>libgmodule</codeph> has APIs that provide a portable method |
|
14 for dynamically loading 'plug-ins' or, in other words, DLLs. Any program that |
|
15 wants to dynamically load modules must be linked to <codeph>libgmodule</codeph>.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
16 <p>In order to use the <codeph>libgmodule</codeph> APIs, the user must check |
|
17 whether dynamic loading of DLLs is supported by the platform by using the <codeph>g_module_supported()</codeph> API |
|
18 which returns TRUE if the dynamic loading of modules is supported. P.I.P.S. |
|
19 provides the implementation of <codeph>libdl</codeph>, where dynamic loading |
|
20 of modules is supported, but to write code which runs across platforms the |
|
21 user must do a check before using the <codeph>libgmodule</codeph> APIs. </p> |
|
22 <p>If the dynamic loading of DLLs is supported, use <codeph>g_module_open()</codeph> to |
|
23 open the module. It takes the name of the module as the first argument and |
|
24 the flags as the second argument.</p> |
|
25 <note><codeph>G_MODULE_BIND_LOCAL</codeph> is the only flag currently supported. |
|
26 The other flags are not supported. If the user specifies any other flag, the |
|
27 module is loaded using the flag <codeph>G_MODULE_BIND_LOCAL</codeph> and not |
|
28 by the user-specified flag.</note> |
|
29 <p><b><codeph>GModule * g_module_open(const gchar *file_name, GModuleFlags |
|
30 flags);</codeph></b></p> |
|
31 <ul> |
|
32 <li><p><b><codeph>file_name</codeph>:</b> The name of the file containing |
|
33 the module.</p></li> |
|
34 <li><p><b><codeph>flags</codeph>:</b> The flags used for opening the module. </p></li> |
|
35 </ul> |
|
36 <p>Once the module is opened, the user can find the module symbols (for example,. |
|
37 function names) using the function </p> |
|
38 <p><codeph>g_module_symbol()</codeph>.</p> |
|
39 <p><b><codeph>gboolean g_module_symbol (GModule *module, const gchar *symbol_name, |
|
40 gpointer *symbol);</codeph></b></p> |
|
41 <ul> |
|
42 <li><p><b><codeph>*module</codeph>:</b> This is a pointer returned when a |
|
43 module is opened using <codeph>g_module_open()</codeph>.</p></li> |
|
44 <li><p><b><codeph>symbol_name</codeph>:</b> This is the ordinal number of |
|
45 the symbol that one wants to open. There is a difference between Symbian GLib |
|
46 and OSS GLib; as in Linux the <codeph>symbol_name</codeph> is the name of |
|
47 the symbol and not a number. The ordinal number must be passed as a string |
|
48 and not a number.</p></li> |
|
49 <li><p><b><codeph>symbol</codeph>:</b> This is the pointer to the symbol value </p></li> |
|
50 </ul> |
|
51 <p>The <codeph>GModule</codeph> can be closed by using the <codeph>g_module_close()</codeph> API. |
|
52 This API returns TRUE if it successfully closed the module; else it returns |
|
53 FALSE.</p> |
|
54 <p><b><codeph>gboolean g_module_close(GModule *module);</codeph></b></p> |
|
55 <ul> |
|
56 <li><p><b><codeph>*module</codeph></b> The <codeph>GModule</codeph> to close. </p></li> |
|
57 </ul> |
|
58 <p>The following example code explains the usage of the <codeph>libgmodule</codeph> APIs. |
|
59 It opens a module <filepath>libmoduletestplugin_a.dll</filepath> and uses |
|
60 its <codeph>gplugin_a_func1()</codeph> API which is ordinal number 1. Finally, |
|
61 the module is closed.</p> |
|
62 <codeblock xml:space="preserve">#include <gmodule.h> |
|
63 #include <glib.h> |
|
64 typedef int (*SimpleFunc) (void); |
|
65 |
|
66 int main() |
|
67 { |
|
68 GModule *module = NULL; |
|
69 gpointer func; |
|
70 SimpleFunc f_a; |
|
71 int retVal; |
|
72 |
|
73 if (!g_module_supported()) |
|
74 { |
|
75 g_print ("Dynamic Opening of modules is not supported"); |
|
76 return 1; |
|
77 } |
|
78 |
|
79 /* G_MODULE_BIND_LAZY is overridden and the module is opened with |
|
80 * flag G_MODULE_BIND_LOCAL |
|
81 */ |
|
82 module = g_module_open("libmoduletestplugin_a.dll",G_MODULE_BIND_LAZY); |
|
83 |
|
84 // 1 is the ordinal number for gplugin_a_func1 |
|
85 if(module && g_module_symbol(module, "1" ,&func)) |
|
86 { |
|
87 f_a = (SimpleFunc)func; |
|
88 retVal = f_a(); |
|
89 g_print("Function at ordinal number 1 of module libgmodule_a returns %d",retVal); |
|
90 } |
|
91 else |
|
92 { |
|
93 g_print("Error quering symbol at ordinal number 1"); |
|
94 return 1; |
|
95 } |
|
96 |
|
97 return 0; |
|
98 }</codeblock> |
|
99 <p>See the <b>Libgmodule APIs</b> section in <xref href="GUID-4ADD8234-4AFD-4E80-94A4-AC018FE83276.dita">Differences |
|
100 between OSS and Symbian GLib</xref> for more details about <codeph>libgmodule</codeph> limitations |
|
101 in the Symbian GLib implementation. </p> |
|
102 </conbody></concept> |