CrystalSpace

Public API Reference

Shared Class Facility (SCF)

Classes

struct  iBase
 This is the basic interface: all other interfaces should be derived from this one, this will allow us to always use at least some minimal functionality given any interface pointer. More...
struct  iComponent
 This interface describes a generic component in Crystal Space. More...
struct  iFactory
 iFactory is an interface that is used to create instances of shared classes. More...
struct  iObjectRegistry
 This interface serves as a registry of other objects. More...
struct  iObjectRegistryIterator
 Use an instance of this class to iterate over objects in the object registry. More...
struct  iPluginIterator
 An iterator to iterate over all plugins in the plugin manager. More...
struct  iPluginManager
 This is the plugin manager. More...
struct  iSCF
 iSCF is the interface that allows using SCF functions from shared classes. More...
class  scfFakeInterface< If >
 Fugly helper to resolve some bad situations. More...
class  scfImplementation< Class >
 Baseclass for the SCF implementation templates. More...
class  scfImplementationHelper
 Various helpers for scfImplementation. More...
class  scfImplementationPooled< Super, Allocator, Locked >
 Derive an SCF implementation from this class to have it pooled. More...
struct  scfInterfaceMetadata
 Metadata about a single interface implemented within a class. More...
struct  scfInterfaceMetadataList
 A chain list of metadata for interfaces implemented within a class. More...
class  scfInterfaceTraits< Interface >
 Interface information query class. More...

Defines

#define CS_QUERY_PLUGIN_CLASS(Object, ClassID, Interface)   csQueryPluginClass<Interface> (Object, ClassID)
 Compatbility macro.
#define SCF_CONSTRUCT_VERSION(Major, Minor, Micro)   ((Major << 24) | (Minor << 16) | Micro)
 Use this macro to construct interface version numbers.
#define SCF_DEFINE_FACTORY_FUNC_REGISTRATION(Class)
 Define the C++ class needed to register an SCF class, but don't do any automatic registration.
#define SCF_IMPLEMENT_FACTORY(Class)
 The SCF_IMPLEMENT_FACTORY macro is used to define a factory for one of exported classes.
#define SCF_IMPLEMENT_FACTORY_CREATE(Class)
 The SCF_IMPLEMENT_FACTORY_CREATE macro is used to define a factory for one of exported classes.
#define SCF_IMPLEMENT_FACTORY_FINIS(Class)
 The SCF_IMPLEMENT_FACTORY_FINIS macro defines finalization code for a plugin module.
#define SCF_IMPLEMENT_FACTORY_INIT(Class)
 The SCF_IMPLEMENT_FACTORY_INIT macro defines initialization code for a plugin module.
#define SCF_INTERFACE(Name, Major, Minor, Micro)
 SCF_INTERFACE can be used to define an interface's version number; you should specify interface name and major, minor and micro version components.
#define SCF_PRINT_CALL_ADDRESS
 Macro for getting the address we were called from (stack backtracing).
#define SCF_REGISTER_FACTORY_FUNC(Class)
 Used in conjunction with SCF_REGISTER_STATIC_LIBRARY to ensure that a reference to the class(es) registered via SCF_REGISTER_STATIC_LIBRARY are actually linked into the application.
#define SCF_REGISTER_STATIC_CLASS(Class, Ident, Desc, Dep)
 Automatically register a built-in class with SCF during startup.
#define SCF_REGISTER_STATIC_LIBRARY(Module, MetaInfo)
 Automatically register a static library with SCF during startup.
#define SCF_TRACE(x)
 Macro for typing debug strings: Add #define SCF_DEBUG at the top of modules you want to track miscelaneous SCF activity and recompile.
#define SCF_USE_STATIC_PLUGIN(Module)
 Register a statically linked plugin.
#define SCF_VERSION(Name, Major, Minor, Micro)
 FOR COMPATIBILITY! SCF_VERSION can be used to define an interface's version number; you should specify interface name and major, minor and micro version components.

Typedefs

typedef iBase *(* scfFactoryFunc )(iBase *)
 Type of factory function which creates an instance of an SCF class.
typedef unsigned long scfInterfaceID
 Type of registered interface handle used by iBase::QueryInterface().
typedef int scfInterfaceVersion
 Type of interface version used by iBase::QueryInterface().

Enumerations

enum  {
  SCF_VERBOSE_NONE = 0, SCF_VERBOSE_PLUGIN_SCAN = 1 << 0, SCF_VERBOSE_PLUGIN_LOAD = 1 << 1, SCF_VERBOSE_PLUGIN_REGISTER = 1 << 2,
  SCF_VERBOSE_CLASS_REGISTER = 1 << 3, SCF_VERBOSE_ALL = ~0
}
 

SCF verbosity flags.

More...

Functions

template<class Interface >
csPtr< Interface > csLoadPlugin (iObjectRegistry *object_reg, const char *ClassID, bool report=true)
 Tell plugin manager to load a plugin (and its dependencies).
template<class Interface >
csPtr< Interface > csLoadPlugin (iPluginManager *mgr, const char *ClassID, bool report=true, bool returnLoadedInstance=false)
 Tell plugin manager to load a plugin (and its dependencies).
csPtr< iComponentcsLoadPluginAlways (iPluginManager *mgr, const char *ClassID, bool report=true)
 Same as csLoadPlugin() but does not bother asking for a interface.
template<class Interface >
csPtr< Interface > csLoadPluginCheck (iObjectRegistry *object_reg, const char *ClassID, bool report=true)
 Tell plugin manager to load a plugin but first check if the plugin is not already loaded.
template<class Interface >
csPtr< Interface > csLoadPluginCheck (iPluginManager *mgr, const char *ClassID, bool report=true)
 Tell plugin manager to load a plugin but first check if the plugin is not already loaded.
template<class Interface >
csPtr< Interface > csQueryPluginClass (iPluginManager *mgr, const char *ClassID)
 Find a plugin by its class ID.
template<class Interface >
csPtr< Interface > csQueryRegistryOrLoad (iObjectRegistry *Reg, const char *classID, bool report=true)
 Use this macro to query the object registry, loading a plugin if needed.
static bool scfCompatibleVersion (scfInterfaceVersion iVersion, scfInterfaceVersion iItfVersion)
 This function checks whenever an interface is compatible with given version.
template<class Interface >
csPtr< Interface > scfCreateInstance (char const *const ClassID)
 Handy function to create an instance of a shared class.
void scfInitialize (int argc, const char *const argv[], bool scanDefaultPluginPaths=true)
 This function should be called to initialize client SCF library.
void scfInitialize (csPathsList const *pluginPaths, unsigned int verbose=SCF_VERBOSE_NONE)
 This function should be called to initialize client SCF library.
template<class Interface , class ClassPtr >
csPtr< Interface > scfQueryInterface (ClassPtr object)
 Helper function around iBase::QueryInterface.
template<class Interface , class ClassPtr >
csPtr< Interface > scfQueryInterfaceSafe (ClassPtr object)
 Helper function around iBase::QueryInterface which also does null-check of object.



void scfRegisterStaticClass (scfFactoryFunc, const char *iClassID, const char *Description, const char *Dependencies=0)
 Register a static class.
void scfRegisterStaticClasses (char const *xml)
 Register a static class.
void scfRegisterStaticFactoryFunc (scfFactoryFunc, const char *FactClass)
 Register a static class.

Some examples

 struct iFoo : virtual public iBase {
   SCF_INTERFACE(iFoo,0,0,1);
 };
 
 struct iBar : virtual public iBase {
   SCF_INTERFACE(iFoo,0,0,1);
 };
 
 class Foo : public scfImplementation1<Foo,iFoo>
 {
 public:
   Foo() : scfImplementationType(this) {}
   Foo(int, int) : scfImplementationType(0,0) {}
 };
 
 class Bar : public scfImplementationExt1<Bar,Foo,iBar>
 {
 public:
   Bar() : scfImplementationType(0) {}
   Bar(int x, int y) : scfImplementationType(0,x,y) {}
 };

Define Documentation

#define CS_QUERY_PLUGIN_CLASS ( Object,
ClassID,
Interface   )     csQueryPluginClass<Interface> (Object, ClassID)

Compatbility macro.

See also:
csQueryPluginClass<Interface> (Object, ClassID);

Definition at line 244 of file plugin.h.

#define SCF_CONSTRUCT_VERSION ( Major,
Minor,
Micro   )     ((Major << 24) | (Minor << 16) | Micro)

Use this macro to construct interface version numbers.

Definition at line 84 of file scf_interface.h.

#define SCF_DEFINE_FACTORY_FUNC_REGISTRATION ( Class   ) 
Value:
CS_EXPORTED_FUNCTION iBase* CS_EXPORTED_NAME(Class,_Create)(iBase*);    \
  class Class##_StaticInit                                              \
  {                                                                     \
  public:                                                               \
    Class##_StaticInit()                                                \
    {                                                                   \
      scfRegisterStaticFactoryFunc (CS_EXPORTED_NAME(Class,_Create),    \
        #Class);                                                        \
    }                                                                   \
  };

Define the C++ class needed to register an SCF class, but don't do any automatic registration.

Definition at line 197 of file scf.h.

#define SCF_IMPLEMENT_FACTORY ( Class   ) 
Value:

The SCF_IMPLEMENT_FACTORY macro is used to define a factory for one of exported classes.

You can define the function manually, of course, if the constructor for your class has some specific constructor arguments (that is, more than one iBase* argument).

Definition at line 152 of file scf.h.

#define SCF_IMPLEMENT_FACTORY_CREATE ( Class   ) 
Value:
CS_EXPORTED_FUNCTION                                                    \
iBase* CS_EXPORTED_NAME(Class,_Create)(iBase *iParent)                  \
{                                                                       \
  iBase *ret = new Class (iParent);                                     \
  SCF_TRACE (("  %p = new %s ()\n", ret, #Class));                      \
  return ret;                                                           \
}

The SCF_IMPLEMENT_FACTORY_CREATE macro is used to define a factory for one of exported classes.

You can define the function manually, of course, if the constructor for your class has some specific constructor arguments (that is, more than one iBase* argument).

Definition at line 137 of file scf.h.

#define SCF_IMPLEMENT_FACTORY_FINIS ( Class   ) 
Value:
CS_EXPORTED_FUNCTION                                                    \
void CS_EXPORTED_NAME(Class,_scfFinalize)()                             \
{                                                                       \
CS_STATIC_VARIABLE_CLEANUP                                              \
}

The SCF_IMPLEMENT_FACTORY_FINIS macro defines finalization code for a plugin module.

As with SCF_IMPLEMENT_FACTORY_INIT, only one instance of this function will be invoked to finalize the module.

Definition at line 124 of file scf.h.

#define SCF_IMPLEMENT_FACTORY_INIT ( Class   ) 
Value:
static inline void Class ## _scfUnitInitialize(iSCF* SCF)               \
{ iSCF::SCF = SCF; }                                                    \
CS_EXPORTED_FUNCTION                                                    \
void CS_EXPORTED_NAME(Class,_scfInitialize)(iSCF* SCF)                  \
{ Class ## _scfUnitInitialize(SCF); }

The SCF_IMPLEMENT_FACTORY_INIT macro defines initialization code for a plugin module.

This function should set the plugin-global iSCF::SCF variable, and otherwise initialize the plugin module. Although a version of this function will be created for each SCF factory exported by the plugin, SCF will call one, and only one, to perform the plugin initialization. The choice of which function will be invoked to initialize the plugin is an SCF implementation detail. You should not attempt to predict which class_scfInitialize() function will be used, nor should use try to sway SCF's choice. Implementation note: There are some rare instances where a particularly picky (and probably buggy) compiler does not allow C++ expressions within a function declared `extern "C"'. For this reason, the iSCF::SCF variable is instead initialized in the Class_scfUnitInitialize() function which is not qualified as `extern "C"'.

Definition at line 111 of file scf.h.

#define SCF_INTERFACE ( Name,
Major,
Minor,
Micro   ) 
Value:
struct InterfaceTraits {                                  \
  CS_DEPRECATION_WARNINGS_DISABLE                         \
  typedef Name InterfaceType;                             \
  CS_DEPRECATION_WARNINGS_ENABLE                          \
  CS_FORCEINLINE static scfInterfaceVersion GetVersion() \
  { return SCF_CONSTRUCT_VERSION(Major, Minor, Micro); }  \
  CS_FORCEINLINE static char const * GetName() { return #Name; }  \
}

SCF_INTERFACE can be used to define an interface's version number; you should specify interface name and major, minor and micro version components.

This way:

 struct iSomething : public iBase
 {
 public:
   SCF_INTERFACE(iSomething, 0, 0, 1);
   ...
 };
 

Definition at line 72 of file scf_interface.h.

#define SCF_PRINT_CALL_ADDRESS

Macro for getting the address we were called from (stack backtracing).

This works ONLY For GCC >= 2.8.0

Definition at line 79 of file scf.h.

#define SCF_REGISTER_FACTORY_FUNC ( Class   ) 
Value:
SCF_DEFINE_FACTORY_FUNC_REGISTRATION(Class)                             \
  Class##_StaticInit Class##_static_init__;

Used in conjunction with SCF_REGISTER_STATIC_LIBRARY to ensure that a reference to the class(es) registered via SCF_REGISTER_STATIC_LIBRARY are actually linked into the application.

Invoke this macro once for each <implementation> node mentioned in the MetaInfo registered with SCF_REGISTER_STATIC_LIBRARY. Invocations of this macro must appear after the the invocation of SCF_REGISTER_STATIC_LIBRARY.

Definition at line 228 of file scf.h.

#define SCF_REGISTER_STATIC_CLASS ( Class,
Ident,
Desc,
Dep   ) 
Value:
CS_EXPORTED_FUNCTION iBase* CS_EXPORTED_NAME(Class,_Create)(iBase*);    \
  class Class##_StaticInit__                                            \
  {                                                                     \
  public:                                                               \
    Class##_StaticInit__()                                              \
    {                                                                   \
      scfRegisterStaticClass(                                           \
        CS_EXPORTED_NAME(Class,_Create), Ident, Desc, Dep);             \
    }                                                                   \
  } Class##_static_init__;

Automatically register a built-in class with SCF during startup.

When SCF classes are statically linked (vs dynamic linking) they should be referenced from somewhere inside your program, otherwise the static libraries won't be linked into the static executable. This macro defines a dummy variable that registers the class during initialization and ensures that it gets linked into the program

Definition at line 167 of file scf.h.

#define SCF_REGISTER_STATIC_LIBRARY ( Module,
MetaInfo   ) 
Value:
class Module##_StaticInit                                               \
  {                                                                     \
  public:                                                               \
    Module##_StaticInit()                                               \
    {                                                                   \
      scfRegisterStaticClasses (MetaInfo);                              \
    }                                                                   \
  } Module##_static_init__;

Automatically register a static library with SCF during startup.

Employ this macro along with one or more invocations of SCF_REGISTER_FACTORY_FUNC.

Definition at line 183 of file scf.h.

#define SCF_TRACE (  ) 

Macro for typing debug strings: Add #define SCF_DEBUG at the top of modules you want to track miscelaneous SCF activity and recompile.

Definition at line 68 of file scf.h.

#define SCF_USE_STATIC_PLUGIN ( Module   ) 
Value:
namespace csStaticPluginInit                                            \
  {                                                                     \
    class Module { public: Module(); };                                 \
    Module Module##_StaticInit;                                         \
  }

Register a statically linked plugin.

The _static version of the plugin needs to be linked in, too.

Definition at line 213 of file scf.h.

#define SCF_VERSION ( Name,
Major,
Minor,
Micro   ) 
Value:
struct Name;                                               \
template<>                                                 \
class scfInterfaceTraits<Name>                             \
{                                                          \
public:                                                    \
  typedef Name InterfaceType;                              \
  static scfInterfaceVersion GetVersion()                  \
  { return SCF_CONSTRUCT_VERSION(Major, Minor, Micro); }   \
  static char const* GetName ()                            \
  { return #Name; }                                        \
  static scfInterfaceID GetID ()                           \
  { scfInterfaceID& ID = GetMyID ();                       \
    if (ID == (scfInterfaceID)(-1))                        \
    { ID = iSCF::SCF->GetInterfaceID (GetName ());         \
      csStaticVarCleanup (CleanupID);    }                 \
    return ID;                                             \
  }                                                        \
private:                                                   \
  static scfInterfaceID& GetMyID ()                        \
  { static scfInterfaceID ID = (scfInterfaceID)-1; return ID; } \
  static void CleanupID ()                                 \
  { GetMyID () = (scfInterfaceID)-1; }                     \
}

FOR COMPATIBILITY! SCF_VERSION can be used to define an interface's version number; you should specify interface name and major, minor and micro version components.

This way:

 SCF_VERSION (iSomething, 0, 0, 1);
 struct iSomething : public iBase
   ...
 };
 

Notice that SCF_VERSION cannot be used on interfaces in namespaces

Definition at line 503 of file scf_interface.h.


Typedef Documentation

typedef iBase*(* scfFactoryFunc)(iBase *)

Type of factory function which creates an instance of an SCF class.

Definition at line 204 of file scf_interface.h.

typedef unsigned long scfInterfaceID

Type of registered interface handle used by iBase::QueryInterface().

Definition at line 51 of file scf_interface.h.

typedef int scfInterfaceVersion

Type of interface version used by iBase::QueryInterface().

Definition at line 56 of file scf_interface.h.


Enumeration Type Documentation

anonymous enum

SCF verbosity flags.

For use with scfInitialize(). Combine with bitwise-or to select more than one.

Enumerator:
SCF_VERBOSE_NONE 

No diagnostic information.

SCF_VERBOSE_PLUGIN_SCAN 

Directories scanned for plugins.

SCF_VERBOSE_PLUGIN_LOAD 

Plugins loaded and unloaded.

SCF_VERBOSE_PLUGIN_REGISTER 

Plugins discovered and registered.

SCF_VERBOSE_CLASS_REGISTER 

Classes registered within plugins.

SCF_VERBOSE_ALL 

All diagnostic information.

Definition at line 271 of file scf.h.


Function Documentation

template<class Interface >
csPtr<Interface> csLoadPlugin ( iObjectRegistry object_reg,
const char *  ClassID,
bool  report = true 
) [inline]

Tell plugin manager to load a plugin (and its dependencies).

Interface: Desired interface type (ex. iGraphics2D, iVFS, etc.).

Parameters:
object_reg object registry
ClassID The SCF class name (ex. crystalspace.graphics3d.software).

Definition at line 274 of file plugin.h.

template<class Interface >
csPtr<Interface> csLoadPlugin ( iPluginManager mgr,
const char *  ClassID,
bool  report = true,
bool  returnLoadedInstance = false 
) [inline]

Tell plugin manager to load a plugin (and its dependencies).

Interface: Desired interface type (ex. iGraphics2D, iVFS, etc.).

Parameters:
mgr An object that implements iPluginManager.
ClassID The SCF class name (ex. crystalspace.graphics3d.software).

Definition at line 254 of file plugin.h.

csPtr<iComponent> csLoadPluginAlways ( iPluginManager mgr,
const char *  ClassID,
bool  report = true 
) [inline]

Same as csLoadPlugin() but does not bother asking for a interface.

This is useful for unconditionally loading plugins.

Definition at line 338 of file plugin.h.

template<class Interface >
csPtr<Interface> csLoadPluginCheck ( iObjectRegistry object_reg,
const char *  ClassID,
bool  report = true 
) [inline]

Tell plugin manager to load a plugin but first check if the plugin is not already loaded.

Interface: Desired interface type (ex. iGraphics2D, iVFS, etc.).

Parameters:
object_reg object registry
ClassID The SCF class name (ex. crystalspace.graphics3d.software).
report if true then we will report an error in case of error.

Definition at line 311 of file plugin.h.

template<class Interface >
csPtr<Interface> csLoadPluginCheck ( iPluginManager mgr,
const char *  ClassID,
bool  report = true 
) [inline]

Tell plugin manager to load a plugin but first check if the plugin is not already loaded.

Interface: Desired interface type (ex. iGraphics2D, iVFS, etc.).

Parameters:
mgr An object that implements iPluginManager.
ClassID The SCF class name (ex. crystalspace.graphics3d.software).

Definition at line 291 of file plugin.h.

template<class Interface >
csPtr<Interface> csQueryPluginClass ( iPluginManager mgr,
const char *  ClassID 
) [inline]

Find a plugin by its class ID.

First the plugin with requested class identifier is found, and after this it is queried for the respective interface; if it does not implement the requested interface, 0 is returned. Interface: Desired interface type (ex. iGraphics2D, iVFS, etc.).

Parameters:
mgr An object that implements iPluginManager.
ClassID The SCF class name (ex. crystalspace.graphics3d.software).

Definition at line 231 of file plugin.h.

template<class Interface >
csPtr<Interface> csQueryRegistryOrLoad ( iObjectRegistry Reg,
const char *  classID,
bool  report = true 
) [inline]

Use this macro to query the object registry, loading a plugin if needed.

If an object with a given interface exists in an object registry, get that object from the registry. If the registry query fails, try to load a plugin and get the interface from there. If that succeeds, the interface is added to the registry for future use and given a tag the same name as the requested interface. Example use:

 csRef<iDynamics> dynamic_system = csQueryRegistryOrLoad<iDynamics> (
        object_reg, "crystalspace.dynamics.ode");
Parameters:
Reg The object registry (of type iObjectRegistry).
classID The requested SCF class name (ex. "crystalspace.dynamice.ode")
report if true then we will report an error in case of error.
Todo:
This probably ought to be made more thread-safe by locking the object registry if possible.
Returns:
a reference to the requested interface if successful. Otherwise this function returns 0.

Definition at line 370 of file plugin.h.

static bool scfCompatibleVersion ( scfInterfaceVersion  iVersion,
scfInterfaceVersion  iItfVersion 
) [static]

This function checks whenever an interface is compatible with given version.

SCF uses the following comparison criteria: if the major version numbers are equal and required minor and micro version is less or equal than target version minor and micro numbers, the versions are considered compatible.

Definition at line 94 of file scf_interface.h.

template<class Interface >
csPtr<Interface> scfCreateInstance ( char const *const   ClassID  )  [inline]

Handy function to create an instance of a shared class.

Definition at line 369 of file scf.h.

void scfInitialize ( int  argc,
const char *const   argv[],
bool  scanDefaultPluginPaths = true 
)

This function should be called to initialize client SCF library.

If scanDefaultPluginPaths is true the default plugin paths provided by csGetPluginPaths() are scanned. Otherwise, no plugin scanning is done. In this case the csPathsList* version of scfInitialize() should be used if some paths should be scanned for plugins.

void scfInitialize ( csPathsList const *  pluginPaths,
unsigned int  verbose = SCF_VERBOSE_NONE 
)

This function should be called to initialize client SCF library.

If a number of plugin paths are provided, the directories will be scanned for plugins and their SCF-related registry data will be retrieved. The root node within the registry data document should be named "plugin", and the SCF-related information should be in a child node of the root named "scf". It is legal to call scfInitialize more than once (possibly providing a different set of directories each time).

Parameters:
pluginPaths Directories that will be scanned for plugins. If this parameter is 0, the paths returned by csGetPluginPaths() will be scanned.
verbose One or more of the SCF_VERBOSE_FOO flags combined with bitwise-or which control SCF verbosity.
template<class Interface , class ClassPtr >
csPtr<Interface> scfQueryInterface ( ClassPtr  object  )  [inline]

Helper function around iBase::QueryInterface.

Definition at line 330 of file scf.h.

template<class Interface , class ClassPtr >
csPtr<Interface> scfQueryInterfaceSafe ( ClassPtr  object  )  [inline]

Helper function around iBase::QueryInterface which also does null-check of object.

Definition at line 359 of file scf.h.

void scfRegisterStaticClass ( scfFactoryFunc  ,
const char *  iClassID,
const char *  Description,
const char *  Dependencies = 0 
)

Register a static class.

This needs extra handling since they require automatic registration even when SCF is initialized after it was possibly shut down previously. The static class info is stored and read out later when SCF is initialized.

void scfRegisterStaticClasses ( char const *  xml  ) 

Register a static class.

This needs extra handling since they require automatic registration even when SCF is initialized after it was possibly shut down previously. The static class info is stored and read out later when SCF is initialized.

void scfRegisterStaticFactoryFunc ( scfFactoryFunc  ,
const char *  FactClass 
)

Register a static class.

This needs extra handling since they require automatic registration even when SCF is initialized after it was possibly shut down previously. The static class info is stored and read out later when SCF is initialized.


Generated for Crystal Space 2.0 by doxygen 1.6.1