/src/wrappers/glib/library/core/glib_dynamic_loading_of_modules.e
Specman e | 303 lines | 2 code | 97 blank | 204 comment | 0 complexity | 07821c677096ee5faec35f0b765dd454 MD5 | raw file
1deferred class GLIB_DYNAMIC_LOADING_OF_MODULES 2 3-- Dynamic Loading of Modules 4 5-- Dynamic Loading of Modules -- portable method for dynamically loading 6-- 'plug-ins'. 7 8-- Synopsis 9 10 11-- #include <gmodule.h> 12 13 14-- GModule; 15-- gboolean g_module_supported (void); 16-- gchar* g_module_build_path (const gchar *directory, 17-- const gchar *module_name); 18-- GModule* g_module_open (const gchar *file_name, 19-- GModuleFlags flags); 20-- enum GModuleFlags; 21-- gboolean g_module_symbol (GModule *module, 22-- const gchar *symbol_name, 23-- gpointer *symbol); 24-- const gchar* g_module_name (GModule *module); 25-- void g_module_make_resident (GModule *module); 26-- gboolean g_module_close (GModule *module); 27-- const gchar* g_module_error (void); 28 29-- const gchar* (*GModuleCheckInit) (GModule *module); 30-- void (*GModuleUnload) (GModule *module); 31-- #define G_MODULE_SUFFIX 32-- #define G_MODULE_EXPORT 33-- #define G_MODULE_IMPORT 34 35-- Description 36 37-- These functions provide a portable way to dynamically load object files (commonly 38-- known as 'plug-ins'). The current implementation supports all systems that 39-- provide an implementation of dlopen() (e.g. Linux/Sun), as well as HP-UX via its 40-- shl_load() mechanism, and Windows platforms via DLLs. 41 42-- A program which wants to use these functions must be linked to the libraries 43-- output by the command pkg-config --libs gmodule-2.0. 44 45-- To use them you must first determine whether dynamic loading is supported on the 46-- platform by calling g_module_supported(). If it is, you can open a module with 47-- g_module_open(), find the module's symbols (e.g. function names) with 48-- g_module_symbol(), and later close the module with g_module_close(). 49-- g_module_name() will return the file name of a currently opened module. 50 51-- If any of the above functions fail, the error status can be found with 52-- g_module_error(). 53 54-- The GModule implementation features reference counting for opened modules, and 55-- supports hook functions within a module which are called when the module is 56-- loaded and unloaded (see GModuleCheckInit and GModuleUnload). 57 58-- If your module introduces static data to common subsystems in the running 59-- program, e.g. through calling g_quark_from_static_string ("my-module-stuff"), it 60-- must ensure that it is never unloaded, by calling g_module_make_resident(). 61 62-- Example 12. Calling a function defined in a GModule 63 64-- /* the function signature for 'say_hello' */ 65-- typedef void (* SayHelloFunc) (const char *message); 66 67-- gboolean 68-- just_say_hello (const char *filename, GError **error) 69-- { 70-- SayHelloFunc say_hello; 71-- GModule *module; 72 73-- module = g_module_open (filename, G_MODULE_BIND_LAZY); 74-- if (!module) 75-- { 76-- g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH, 77-- "%s", g_module_error ()); 78-- return FALSE; 79-- } 80 81-- if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello)) 82-- { 83-- g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN, 84-- "%s: %s", filename, g_module_error ()); 85-- if (!g_module_close (module)) 86-- g_warning ("%s: %s", filename, g_module_error ()); 87-- return FALSE; 88-- } 89 90-- /* call our function in the module */ 91-- say_hello ("Hello world!"); 92 93-- if (!g_module_close (module)) 94-- g_warning ("%s: %s", filename, g_module_error ()); 95 96-- return TRUE; 97-- } 98 99-- Details 100 101-- GModule 102 103-- typedef struct _GModule GModule; 104 105-- The GModule struct is an opaque data structure to represent a Dynamically-Loaded 106-- Module. It should only be accessed via the following functions. 107 108-- --------------------------------------------------------------------------------- 109 110-- g_module_supported () 111 112-- gboolean g_module_supported (void); 113 114-- Checks if modules are supported on the current platform. 115 116-- Returns : TRUE if modules are supported. 117 118-- --------------------------------------------------------------------------------- 119 120-- g_module_build_path () 121 122-- gchar* g_module_build_path (const gchar *directory, 123-- const gchar *module_name); 124 125-- A portable way to build the filename of a module. The platform-specific prefix 126-- and suffix are added to the filename, if needed, and the result is added to the 127-- directory, using the correct separator character. 128 129-- The directory should specify the directory where the module can be found. It can 130-- be NULL or an empty string to indicate that the module is in a standard 131-- platform-specific directory, though this is not recommended since the wrong 132-- module may be found. 133 134-- For example, calling g_module_build_path() on a Linux system with a directory of 135-- /lib and a module_name of "mylibrary" will return /lib/libmylibrary.so. On a 136-- Windows system, using \Windows as the directory it will return 137-- \Windows\mylibrary.dll. 138 139-- directory : the directory where the module is. This can be NULL or the empty 140-- string to indicate that the standard platform-specific directories 141-- will be used, though that is not recommended. 142-- module_name : the name of the module. 143-- Returns : the complete path of the module, including the standard library 144-- prefix and suffix. This should be freed when no longer needed. 145 146-- --------------------------------------------------------------------------------- 147 148-- g_module_open () 149 150-- GModule* g_module_open (const gchar *file_name, 151-- GModuleFlags flags); 152 153-- Opens a module. If the module has already been opened, its reference count is 154-- incremented. 155 156-- First of all g_module_open() tries to open file_name as a module. If that fails 157-- and file_name has the ".la"-suffix (and is a libtool archive) it tries to open 158-- the corresponding module. If that fails and it doesn't have the proper module 159-- suffix for the platform (G_MODULE_SUFFIX), this suffix will be appended and the 160-- corresponding module will be opended. If that fails and file_name doesn't have 161-- the ".la"-suffix, this suffix is appended and g_module_open() tries to open the 162-- corresponding module. If eventually that fails as well, NULL is returned. 163 164-- file_name : the name of the file containing the module, or NULL to obtain a 165-- GModule representing the main program itself. 166-- flags : the flags used for opening the module. This can be the logical OR of 167-- any of the GModuleFlags. 168-- Returns : a GModule on success, or NULL on failure. 169 170-- --------------------------------------------------------------------------------- 171 172-- enum GModuleFlags 173 174-- typedef enum 175-- { 176-- G_MODULE_BIND_LAZY = 1 << 0, 177-- G_MODULE_BIND_LOCAL = 1 << 1, 178-- G_MODULE_BIND_MASK = 0x03 179-- } GModuleFlags; 180 181-- Flags passed to g_module_open(). Note that these flags are not supported on all 182-- platforms. 183 184-- G_MODULE_BIND_LAZY specifies that symbols are only resolved when needed. The 185-- default action is to bind all symbols when the module is 186-- loaded. 187-- G_MODULE_BIND_LOCAL specifies that symbols in the module should not be added to 188-- the global name space. The default action on most platforms 189-- is to place symbols in the module in the global name space, 190-- which may cause conflicts with existing symbols. 191-- G_MODULE_BIND_MASK mask for all flags. 192 193-- --------------------------------------------------------------------------------- 194 195-- g_module_symbol () 196 197-- gboolean g_module_symbol (GModule *module, 198-- const gchar *symbol_name, 199-- gpointer *symbol); 200 201-- Gets a symbol pointer from a module. 202 203-- module : a GModule. 204-- symbol_name : the name of the symbol to find. 205-- symbol : returns the pointer to the symbol value. 206-- Returns : TRUE on success. 207 208-- --------------------------------------------------------------------------------- 209 210-- g_module_name () 211 212-- const gchar* g_module_name (GModule *module); 213 214-- Gets the filename from a GModule. 215 216-- module : a GModule. 217-- Returns : the filename of the module, or "main" if the module is the main program 218-- itself. 219 220-- --------------------------------------------------------------------------------- 221 222-- g_module_make_resident () 223 224-- void g_module_make_resident (GModule *module); 225 226-- Ensures that a module will never be unloaded. Any future g_module_close() calls 227-- on the module will be ignored. 228 229-- module : a GModule to make permanently resident. 230 231-- --------------------------------------------------------------------------------- 232 233-- g_module_close () 234 235-- gboolean g_module_close (GModule *module); 236 237-- Closes a module. 238 239-- module : a GModule to close. 240-- Returns : TRUE on success. 241 242-- --------------------------------------------------------------------------------- 243 244-- g_module_error () 245 246-- const gchar* g_module_error (void); 247 248-- Gets a string describing the last module error. 249 250-- Returns : a string describing the last module error. 251 252-- --------------------------------------------------------------------------------- 253 254-- GModuleCheckInit () 255 256-- const gchar* (*GModuleCheckInit) (GModule *module); 257 258-- Specifies the type of the module initialization function. If a module contains a 259-- function named g_module_check_init() it is called automatically when the module 260-- is loaded. It is passed the GModule structure and should return NULL on success 261-- or a string describing the initialization error. 262 263-- module : the GModule corresponding to the module which has just been loaded. 264-- Returns : NULL on success, or a string describing the initialization error. 265 266-- --------------------------------------------------------------------------------- 267 268-- GModuleUnload () 269 270-- void (*GModuleUnload) (GModule *module); 271 272-- Specifies the type of the module function called when it is unloaded. If a module 273-- contains a function named g_module_unload() it is called automatically when the 274-- module is unloaded. It is passed the GModule structure. 275 276-- module : the GModule about to be unloaded. 277 278-- --------------------------------------------------------------------------------- 279 280-- G_MODULE_SUFFIX 281 282-- #define G_MODULE_SUFFIX "so" 283 284-- Expands to the proper shared library suffix for the current platform without the 285-- leading dot. For the most Unices and Linux this is "so", for some HP-UX versions 286-- this is "sl" and for Windows this is "dll". 287 288-- --------------------------------------------------------------------------------- 289 290-- G_MODULE_EXPORT 291 292-- #define G_MODULE_EXPORT 293 294-- Used to declare functions exported by modules. 295 296-- --------------------------------------------------------------------------------- 297 298-- G_MODULE_IMPORT 299 300-- #define G_MODULE_IMPORT extern 301 302-- Used to declare functions imported from modules. 303end -- class GLIB_DYNAMIC_LOADING_OF_MODULES