[Home]	[About]
[Screenshots]	[Download]
[News]	[Community]
[Documentation]	[Manual]
[Bugs & Requests]	[Wiki]

Plugins Namespace Reference

---

Detailed Description

Plugin Management Utility Library

This is the interface to the cross-platform plugin library.

Basically it replicates the nix dlopen() family of functions, and adds some misc. utilities. (To use the library, include this file, and link against the libplugins library.)

Currently this library supports the dlopen() system found on most Unix-like systems, as well as MS-Windows DLLs and Darwin loadable modules (Mac OS X).

Unix notes: The Plugins::scanDir() function tries to avoid loading the same plugin several times via its version symlinks by skipping files with stuff after the ".so" extension (e.g. "foo.so.1.2.3")

Windows notes: The Plugins::scanDir() function loads files that end in ".DLL".

Darwin notes: The plugins must be Mach MH_BUNDLE files: ie, compiled with the -bundle option. (Attempting to load any other files will cause a crash).

• VUTIL_API int LAZY

  Modes to use with Plugins::open.
  

• VUTIL_API int NOW
• VUTIL_API int GLOBAL

Functions

• VUTIL_API void * open (const char *path, int mode=LAZY)

  Open a plugin (unless already opened) from named file with specified options.
  

• VUTIL_API void * findsym (void *handle, const char *symbol)

  return pointer to a symbol from an opened plugin.
  

• VUTIL_API int close (void *handle)

  Close a plugin.
  

• VUTIL_API const char * error (void)

  Get a description of the last error.
  

• VUTIL_API int scanDir (const std::string &dirname, const char *init_fn_name="plugin_init", void *init_param=NULL)

  Scan a directory and load all files whose filename suffix is correct for this platform.
  

• VUTIL_API int scanDirs (const std::string &dir_paths, const char *init_fn_name, void *init_param)

  Scan multiple directories.
  

• VUTIL_API void closeAll ()

  Close all plugins that have been opened by Plugins::open().
  

• VUTIL_API std::string pluginExt ()

  Standard file extension for a binary plugin.
  

Variables

• std::multiset< void * > sys_plugin_handles
• std::string lastError

  Some implementations might use this.
  

---

Function Documentation

VUTIL_API void* Plugins::open	(	const char *	path,
		int	mode = LAZY
	)

Open a plugin (unless already opened) from named file with specified options.

Parameters:

	path	path to plugin file
	mode	options: Plugins::NOW Resolve all symbols on load. (no effect on Windows) Plugins::LAZY Resolve symbols as they're needed (no effect on Windows) Plugins::GLOBAL Or this with Plugins::NOW or Plugins::LAZY to make symbols available to subsequently loaded plugins. (no effect on Windows)

Returns:

platform-specific handle to plugin, or 0 on error.

VUTIL_API void* Plugins::findsym	(	void *	handle,
		const char *	symbol
	)

return pointer to a symbol from an opened plugin.

Parameters:

	handle	plugin handle, as returned by Plugins::open().
	symbol	name of symbol to search for

Returns:

pointer to symbol, or 0 if no such symbol is found.

VUTIL_API int Plugins::close

(

void *

handle

)

Close a plugin.

Parameters:

handle

handle as returned by Plugins::open().

VUTIL_API const char* Plugins::error

(

void

)

Get a description of the last error.

Referenced by TiXmlDocument::ClearError(), and TiXmlDocument::Error().

VUTIL_API int Plugins::scanDir	(	const std::string &	dirname,
		const char *	init_fn_name = "plugin_init",
		void *	init_param = NULL
	)

Scan a directory and load all files whose filename suffix is correct for this platform.

Parameters:

	dirname	Path to directory to scan.
	init_fn_name	Name of function to find and call in the plugin.
	init_param	A parameter to pass to the plugin init function.

Returns:

-1 If the directory could not be opened.

0 If all plugins were loaded successfully.

>0 The number of files that failed to load as plugins for some reason.

VUTIL_API int Plugins::scanDirs	(	const std::string &	dir_paths,
		const char *	init_fn_name,
		void *	init_param
	)

Scan multiple directories.

Skips any directories that coudn't be opened.

Parameters:

dir_paths

directory names, seperated by ':' (but you can use "\:" for a literal ':')

See also:

scanDir

VUTIL_API void Plugins::closeAll

(

)

Close all plugins that have been opened by Plugins::open().

VUTIL_API std::string Plugins::pluginExt

(

)

Standard file extension for a binary plugin.

---

Variable Documentation

std::multiset<void*> Plugins::sys_plugin_handles

VUTIL_API int Plugins::LAZY

Modes to use with Plugins::open.

VUTIL_API int Plugins::NOW

VUTIL_API int Plugins::GLOBAL

std::string Plugins::lastError

Some implementations might use this.