iSCF Struct Reference
[Shared Class Facility (SCF)]
iSCF is the interface that allows using SCF functions from shared classes.
More...
#include <csutil/scf_interface.h>
Inheritance diagram for iSCF:
Public Member Functions | |
| virtual bool | ClassRegistered (const char *iClassID)=0 |
| Check whenever the class is present in SCF registry. | |
| virtual iBase * | CreateInstance (const char *iClassID)=0 |
| Create an instance of a class that supports given interface. | |
| virtual void | Finish ()=0 |
| This function should be called to finish working with SCF. | |
| virtual const char * | GetClassDependencies (const char *iClassID)=0 |
| Query the dependency list for a class. | |
| virtual const char * | GetClassDescription (const char *iClassID)=0 |
| Query the description of a class. | |
| virtual scfInterfaceID | GetInterfaceID (const char *iInterface)=0 |
| Return the interface ID number that belongs to the given interface. | |
| virtual char const * | GetInterfaceName (scfInterfaceID) const =0 |
| Return the name of an interface given an interface ID. | |
| virtual csRef< iDocument > | GetPluginMetadata (char const *iClassID)=0 |
| Given a registered class name, returns the meta information associated with the plugin module in which the class is implemented. | |
| virtual csRef< iStringArray > | QueryClassList (char const *pattern)=0 |
| Retrieve a list of class names whose prefix matches a pattern string. | |
| virtual bool | RegisterClass (scfFactoryFunc, const char *iClassID, const char *Description, const char *Dependencies=0, const char *context=0)=0 |
| Register a single dynamic class. | |
| virtual bool | RegisterClass (const char *iClassID, const char *iLibraryName, const char *iFactoryClass, const char *Description, const char *Dependencies=0, const char *context=0)=0 |
| Register a single dynamic class (implemented in a shared library). | |
| virtual void | RegisterClasses (const char *pluginPath, iDocument *metadata, const char *context=0)=0 |
| Read additional class descriptions from the given iDocument. | |
| virtual void | RegisterClasses (char const *xml, const char *context=0)=0 |
| A convenience wrapper for RegisterClasses(iDocument). | |
| virtual void | RegisterClasses (iDocument *metadata, const char *context=0)=0 |
| Read additional class descriptions from the given iDocument. | |
| virtual bool | RegisterFactoryFunc (scfFactoryFunc, const char *FactClass)=0 |
| Associate a factory function (the function which instantiates a class) with an implementation name (the value in the <implementation> node of the meta information; also the name of the iFactoryClass in RegisterClass). | |
| virtual bool | RegisterPlugin (const char *path)=0 |
| Register a single plugin. | |
| virtual void | ScanPluginsPath (const char *path, bool recursive=false, const char *context=0)=0 |
| Scan a specified native path for plugins and auto-register them. | |
| virtual void | UnloadUnusedModules ()=0 |
| Unload all unused shared libraries (also called inside scfCreateInstance). | |
| virtual bool | UnregisterClass (const char *iClassID)=0 |
| This function should be called to deregister a class at run-time. | |
Static Public Attributes | |
| static iSCF * | SCF |
| This is the global instance of iSCF. | |
Detailed Description
iSCF is the interface that allows using SCF functions from shared classes.Since there should be just one instance of SCF kernel, the shared classes should not use scfXXX functions directly; instead they should obtain a pointer to an iSCF object and work through that pointer.
Definition at line 149 of file scf_interface.h.
Member Function Documentation
| virtual bool iSCF::ClassRegistered | ( | const char * | iClassID | ) | [pure virtual] |
Check whenever the class is present in SCF registry.
You can use this function to check whenever a class instance creation failed because the class is not present at all in the class registry, or it just doesn't support the requested interface.
| virtual iBase* iSCF::CreateInstance | ( | const char * | iClassID | ) | [pure virtual] |
Create an instance of a class that supports given interface.
The function returns 0 either if such a class ID is not found in class registry, or a object of given class does not support given interface or supports an incompatible version of given interface. If you want to make a difference between these error conditions, you can check whenever such a class exists using scfClassRegistered() function.
The returned pointer will be to a iBase, and thus you need to use scfQueryInterface if you want to get a specific interface.
Referenced by scfCreateInstance().
| virtual void iSCF::Finish | ( | ) | [pure virtual] |
This function should be called to finish working with SCF.
This will not free shared objects but they should not be used anymore after calling this function since this will do a forced free of all loaded shared libraries.
| virtual const char* iSCF::GetClassDependencies | ( | const char * | iClassID | ) | [pure virtual] |
Query the dependency list for a class.
The format of dependency string is implementation-specific, SCF itself does not make any assumptions about the format of the string.
| virtual const char* iSCF::GetClassDescription | ( | const char * | iClassID | ) | [pure virtual] |
Query the description of a class.
NOTE: At least one instance of this class should exist, or the class should be a static class. Otherwise the function will return 0
| virtual scfInterfaceID iSCF::GetInterfaceID | ( | const char * | iInterface | ) | [pure virtual] |
Return the interface ID number that belongs to the given interface.
If the interface is unknown, a new ID is allocated. This number can be used to quickly determine whether two interfaces are equal.
Referenced by scfInterfaceTraits< Interface >::GetID().
| virtual char const* iSCF::GetInterfaceName | ( | scfInterfaceID | ) | const [pure virtual] |
Return the name of an interface given an interface ID.
If the ID is unknown, null is returned.
Given a registered class name, returns the meta information associated with the plugin module in which the class is implemented.
Since the meta information associated with a plugin is extensible, plugin authors are free to attach any additional information they desire, beyond that which is used by SCF itself. This function provides a way for clients to access the additional meta information which plugin authors might choose to publish.
If the specified class is not implemented by a plugin module (for instance, it might be implemented directly by the application), or if plugin module is lacking meta information for some reason, then the returned csRef<> will be invalid. You should check for this condition by invoking csRef<>::IsValid() or simply by using the returned reference in a boolean conditional expression.
Note that it is possible for a single plugin module to export multiple, named SCF classes. The meta information returned by this function belongs to the plugin itself, not to any individual class exported by that plugin. Therefore, if you invoke this method twice for two different classes, and those classes are exported by the same plugin, then the same meta information will be returned by both queries.
If you know the physical path of a plugin, then you can instead invoke csGetPluginMetadata() (csutil/csshlib.h) to retrieve its meta information.
| virtual csRef<iStringArray> iSCF::QueryClassList | ( | char const * | pattern | ) | [pure virtual] |
Retrieve a list of class names whose prefix matches a pattern string.
For example, QueryClassList("crystalspace.sound.loader.") will return a list of class names which begin with the string "crystalspace.sound.loader.". If pattern is zero length or the null pointer, then all registered class names are returned. If any class names match the pattern, then the return value is a list of strings. If no class names match the pattern string, then the returned list is empty.
| virtual bool iSCF::RegisterClass | ( | scfFactoryFunc | , | |
| const char * | iClassID, | |||
| const char * | Description, | |||
| const char * | Dependencies = 0, |
|||
| const char * | context = 0 | |||
| ) | [pure virtual] |
Register a single dynamic class.
This function tells SCF kernel that a specific class is implemented within a specific module (typically a static library, as opposed to a plugin module). You also can provide an application-specific dependency list.
| virtual bool iSCF::RegisterClass | ( | const char * | iClassID, | |
| const char * | iLibraryName, | |||
| const char * | iFactoryClass, | |||
| const char * | Description, | |||
| const char * | Dependencies = 0, |
|||
| const char * | context = 0 | |||
| ) | [pure virtual] |
Register a single dynamic class (implemented in a shared library).
This function tells SCF kernel that a specific class is implemented within a specific shared library. There can be multiple classes within a single shared library. You also can provide an application-specific dependency list. 'context' is an information about the source of the plugin. It primarily affects whether a class conflict is reported. If the same class already exists in the same context, a warning is emitted; if it's in a different context, only there is a notification only in debug mode.
| virtual void iSCF::RegisterClasses | ( | const char * | pluginPath, | |
| iDocument * | metadata, | |||
| const char * | context = 0 | |||
| ) | [pure virtual] |
Read additional class descriptions from the given iDocument.
| virtual void iSCF::RegisterClasses | ( | char const * | xml, | |
| const char * | context = 0 | |||
| ) | [pure virtual] |
A convenience wrapper for RegisterClasses(iDocument).
Assumes that the string input argument is XML, which it wraps in an iDocument and then passes to RegisterClasses(iDocument).
| virtual void iSCF::RegisterClasses | ( | iDocument * | metadata, | |
| const char * | context = 0 | |||
| ) | [pure virtual] |
Read additional class descriptions from the given iDocument.
| virtual bool iSCF::RegisterFactoryFunc | ( | scfFactoryFunc | , | |
| const char * | FactClass | |||
| ) | [pure virtual] |
Associate a factory function (the function which instantiates a class) with an implementation name (the value in the <implementation> node of the meta information; also the name of the iFactoryClass in RegisterClass).
Returns true upon sucess, or false if the class does not exist or already has an associated creation function.
| virtual bool iSCF::RegisterPlugin | ( | const char * | path | ) | [pure virtual] |
Register a single plugin.
- Parameters:
-
path (Almost) fully qualified native path to the plugin binary. 'Almost' because it doesn't have to be the actual binary - it is sufficient if the file name suffix is ".csplugin", no matter what the real extension for binaries on a platform is or whether there actually is an external .csplugin file.
- Returns:
- Whether loading of the plugin was successful.
| virtual void iSCF::ScanPluginsPath | ( | const char * | path, | |
| bool | recursive = false, |
|||
| const char * | context = 0 | |||
| ) | [pure virtual] |
Scan a specified native path for plugins and auto-register them.
| virtual void iSCF::UnloadUnusedModules | ( | ) | [pure virtual] |
Unload all unused shared libraries (also called inside scfCreateInstance).
If you want to be sure that all unused shared libraries are unloaded, call this function. It is automatically invoked inside scfCreateInstance(), thus it is called from time to time if you constantly create new objects.
| virtual bool iSCF::UnregisterClass | ( | const char * | iClassID | ) | [pure virtual] |
This function should be called to deregister a class at run-time.
By calling this function you will remove the description of a class, no matter whenever it is statically or dynamically linked, from the SCF registry.
Member Data Documentation
This is the global instance of iSCF.
On most platforms, this variable is module-global; for instance, the application has an iSCF::SCF variable, and each plugin module has an iSCF::SCF variable, all of which point at the same shared instance of iSCF. On other platforms, though, the variable might truly be global, in which case the variable itself is shared by application and all plugin modules. In actual practice, however, whether the variable's scope is global or only module-global, makes no difference since clients access the shared instance uniformly as iSCF::SCF.
Definition at line 163 of file scf_interface.h.
Referenced by csDebugImageWriter::DebugImageWrite(), scfInterfaceTraits< Interface >::GetID(), and scfCreateInstance().
The documentation for this struct was generated from the following file:
- csutil/scf_interface.h
Generated for Crystal Space by doxygen 1.4.7