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< iComponent > | csLoadPluginAlways (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);
#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 | ) |
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.
#define SCF_IMPLEMENT_FACTORY | ( | Class | ) |
SCF_IMPLEMENT_FACTORY_INIT(Class) \ SCF_IMPLEMENT_FACTORY_FINIS(Class) \ SCF_IMPLEMENT_FACTORY_CREATE(Class)
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).
#define SCF_IMPLEMENT_FACTORY_CREATE | ( | Class | ) |
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).
#define SCF_IMPLEMENT_FACTORY_FINIS | ( | Class | ) |
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.
#define SCF_IMPLEMENT_FACTORY_INIT | ( | Class | ) |
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"'.
#define SCF_INTERFACE | ( | Name, | |||
Major, | |||||
Minor, | |||||
Micro | ) |
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 |
#define SCF_REGISTER_FACTORY_FUNC | ( | Class | ) |
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.
#define SCF_REGISTER_STATIC_CLASS | ( | Class, | |||
Ident, | |||||
Desc, | |||||
Dep | ) |
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
#define SCF_REGISTER_STATIC_LIBRARY | ( | Module, | |||
MetaInfo | ) |
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.
#define SCF_TRACE | ( | x | ) |
#define SCF_USE_STATIC_PLUGIN | ( | Module | ) |
#define SCF_VERSION | ( | Name, | |||
Major, | |||||
Minor, | |||||
Micro | ) |
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:
Function Documentation
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).
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).
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.
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.
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).
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).
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.
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.
csPtr<Interface> scfCreateInstance | ( | char const *const | ClassID | ) | [inline] |
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.
csPtr<Interface> scfQueryInterface | ( | ClassPtr | object | ) | [inline] |
Helper function around iBase::QueryInterface.
csPtr<Interface> scfQueryInterfaceSafe | ( | ClassPtr | object | ) | [inline] |
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.
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