CrystalSpace

Public API Reference

Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

csshlib.h File Reference

Crystal Space cross-platform shared library management. More...

#include "csextern.h"
#include "csutil/ref.h"
#include "csutil/stringarray.h"
#include "iutil/string.h"

Go to the source code of this file.

Low-level shared library support

typedef void * csLibraryHandle
void * csGetLibrarySymbol (csLibraryHandle Handle, char const *iName)
 Return a pointer to a symbol within given shared library.
bool csGetLoadLibraryVerbose ()
 Query if failed dynamic library loads generate verbose messages.
csRef< iStringcsGetPluginMetadata (const char *fullPath, csRef< iDocument > &metadata)
 Retrive a plugin's metadata.
csLibraryHandle csLoadLibrary (char const *iName)
 Load a shared library and return a library handle, which is used later to query and unload the library.
void csPrintLibraryError (char const *iModule)
 Print out the latest dynamic loader error.
csRef< iStringArraycsScanPluginDir (const char *dir, csRef< iStringArray > &plugins, bool recursive=true)
 Scan a given directory for plugins and return a list of the plugin native file names and their respective metadata.
csRef< iStringArraycsScanPluginDirs (csPathsList *dirs, csRef< iStringArray > &plugins)
 Scan some given directories for plugins.
void csSetLoadLibraryVerbose (bool)
 Control whether dynamic library loading messages are verbose or terse.
bool csUnloadLibrary (csLibraryHandle Handle)
 Unload a shared library given its handle.


Detailed Description

Crystal Space cross-platform shared library management.

Definition in file csshlib.h.


Function Documentation

void* csGetLibrarySymbol csLibraryHandle  Handle,
char const *  iName
 

Return a pointer to a symbol within given shared library.

Note that generally Crystal Space needs just one exported symbol from every shared library; the symbol is called {library}_scfInitialize. If your OS is short on features, you may implement querying of just this symbol.

bool csGetLoadLibraryVerbose  ) 
 

Query if failed dynamic library loads generate verbose messages.

csRef<iString> csGetPluginMetadata const char *  fullPath,
csRef< iDocument > &  metadata
 

Retrive a plugin's metadata.

Remarks:
`fullPath' should be either a string returned from csScanPluginDir() or csScanPluginDirs(), or a fully qualified native path of the plugin module. The path suffix should be either .csplugin if the plugin metadata is stored in an external .csplugin file, or it should be the standard suffix of shared libraries or bundles for the platform (for example, .so for Unix; .dll for Windows). If metadata is retrieved successfully for the specified plugin module, metadata.IsValid() will return true, and the `metadata' argument will reference an iDocument containing the data. If no metadata is located or an error occurrs while attempting to retrieve the metadata, metadata.IsValid() return false. If some type of reportable error or warning is encountered, it will be returned from the function as an iString. It is possible for a warning to be issued even if metadata was successfully retrieved. Finally, if metadata.IsValid() returns false and the returned iString is empty, then that indicates simply that the specified path does not correspond to a Crystal Space plugin module. This is a valid condition.

csLibraryHandle csLoadLibrary char const *  iName  ) 
 

Load a shared library and return a library handle, which is used later to query and unload the library.

iName is the FULL path to the library.

void csPrintLibraryError char const *  iModule  ) 
 

Print out the latest dynamic loader error.

This is not strictly required (and on some platforms its just a empty routine) but sometimes it helps to find problems.

csRef<iStringArray> csScanPluginDir const char *  dir,
csRef< iStringArray > &  plugins,
bool  recursive = true
 

Scan a given directory for plugins and return a list of the plugin native file names and their respective metadata.

Parameters:
dir Directory to scan.
plugins Native file names.
recursive Recursively scan all subdirectories.
Remarks:
It is the responsibility of the caller to do any cleaning of metadata and plugins, if desired.

plugins can be 0, a string vector will be created in this case.

Returns:
If any errors occured, a vector of error descriptions.

csRef<iStringArray> csScanPluginDirs csPathsList dirs,
csRef< iStringArray > &  plugins
 

Scan some given directories for plugins.

Accepts the same parameters as csScanPluginDir(), with the exception of dirs.

void csSetLoadLibraryVerbose bool   ) 
 

Control whether dynamic library loading messages are verbose or terse.

When verbose, and a library fails to load, csPrintLibraryError() is invoked to emit detailed diagnostic information regarding the failure. If terse, then a simple message is emitted stating that the library failed to load and instructing the user to use the -verbose command-line option for more details. Verbose messages are enabled by default for debug builds; terse messages for optimized builds.

bool csUnloadLibrary csLibraryHandle  Handle  ) 
 

Unload a shared library given its handle.

The function returns false on error.


Generated for Crystal Space by doxygen 1.4.4