CrystalSpace

Public API Reference

csutil/scf.h
Go to the documentation of this file.
00001 /*
00002     Crystal Space Shared Class Facility (SCF)
00003     Copyright (C) 1999 by Andrew Zabolotny
00004               (C) 2005 by Marten Svanfeldt
00005               (C) 2005 by Michael Adams
00006 
00007     This library is free software; you can redistribute it and/or
00008     modify it under the terms of the GNU Library General Public
00009     License as published by the Free Software Foundation; either
00010     version 2 of the License, or (at your option) any later version.
00011 
00012     This library is distributed in the hope that it will be useful,
00013     but WITHOUT ANY WARRANTY; without even the implied warranty of
00014     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00015     Library General Public License for more details.
00016 
00017     You should have received a copy of the GNU Library General Public
00018     License along with this library; if not, write to the Free
00019     Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00020 */
00021 
00022 #ifndef __CSSCF_H__
00023 #define __CSSCF_H__
00024 
00025 #include "csextern.h"
00026 
00027 #include "csutil/array.h"
00028 #include "csutil/ref.h"
00029 
00038 class csPathsList;
00039 
00040 #ifndef CS_TYPENAME
00041   #ifdef CS_REF_TRACKER
00042    #include <typeinfo>
00043    #define CS_TYPENAME(x)                   typeid(x).name()
00044   #else
00045    #define CS_TYPENAME(x)                   0
00046   #endif
00047 #endif
00048 
00049 // INTERFACE DEFINITIONS
00050 #include "csutil/scf_interface.h"
00051 // NEW STYLE IMPLEMENTATION
00052 //#include "csutil/scf_implementation.h"
00053 
00054 
00055 //-- Helper macros
00056 
00061 #ifdef SCF_DEBUG
00062 #  define SCF_TRACE(x)                                                  \
00063    {                                                                    \
00064      printf ("SCF [%s:%d]:\n", __FILE__, (int)__LINE__);                \
00065      printf x; SCF_PRINT_CALL_ADDRESS                                   \
00066    }
00067 #else
00068 #  define SCF_TRACE(x)
00069 #endif
00070 
00075 #if (__GNUC__ >= 3) || ((__GNUC__ >= 2) && (__GNUC_MINOR__ >= 8))
00076 #  define SCF_PRINT_CALL_ADDRESS                                        \
00077    printf ("  Called from address %p\n", __builtin_return_address (0));
00078 #else
00079 #  define SCF_PRINT_CALL_ADDRESS
00080 #endif
00081 
00097 #ifdef CS_MEMORY_TRACKER
00098 #include "memdebug.h" // needed for mtiRegisterModule
00099 // This special version of SCF_IMPLEMENT_FACTORY_INIT will make sure that
00100 // the memory tracker for this plugin is implemented.
00101 #define SCF_IMPLEMENT_FACTORY_INIT(Class)                               \
00102 static inline void Class ## _scfUnitInitialize(iSCF* SCF)               \
00103 {                                                                       \
00104   iSCF::SCF = SCF;                                                      \
00105   CS::Debug::MemTracker::RegisterModule (#Class);                       \
00106 }                                                                       \
00107 CS_EXPORTED_FUNCTION                                                    \
00108 void CS_EXPORTED_NAME(Class,_scfInitialize)(iSCF* SCF)                  \
00109 { Class ## _scfUnitInitialize(SCF); }
00110 #else
00111 #define SCF_IMPLEMENT_FACTORY_INIT(Class)                               \
00112 static inline void Class ## _scfUnitInitialize(iSCF* SCF)               \
00113 { iSCF::SCF = SCF; }                                                    \
00114 CS_EXPORTED_FUNCTION                                                    \
00115 void CS_EXPORTED_NAME(Class,_scfInitialize)(iSCF* SCF)                  \
00116 { Class ## _scfUnitInitialize(SCF); }
00117 #endif
00118 
00124 #define SCF_IMPLEMENT_FACTORY_FINIS(Class)                              \
00125 CS_EXPORTED_FUNCTION                                                    \
00126 void CS_EXPORTED_NAME(Class,_scfFinalize)()                             \
00127 {                                                                       \
00128 CS_STATIC_VARIABLE_CLEANUP                                              \
00129 }
00130 
00137 #define SCF_IMPLEMENT_FACTORY_CREATE(Class)                             \
00138 CS_EXPORTED_FUNCTION                                                    \
00139 iBase* CS_EXPORTED_NAME(Class,_Create)(iBase *iParent)                  \
00140 {                                                                       \
00141   iBase *ret = new Class (iParent);                                     \
00142   SCF_TRACE (("  %p = new %s ()\n", ret, #Class));                      \
00143   return ret;                                                           \
00144 }
00145 
00152 #define SCF_IMPLEMENT_FACTORY(Class)                                    \
00153   SCF_IMPLEMENT_FACTORY_INIT(Class)                                     \
00154   SCF_IMPLEMENT_FACTORY_FINIS(Class)                                    \
00155   SCF_IMPLEMENT_FACTORY_CREATE(Class)
00156 
00157 #define SCF_STATIC_CLASS_CONTEXT      "*static*"
00158 
00167 #define SCF_REGISTER_STATIC_CLASS(Class,Ident,Desc,Dep)                 \
00168   CS_EXPORTED_FUNCTION iBase* CS_EXPORTED_NAME(Class,_Create)(iBase*);  \
00169   class Class##_StaticInit__                                            \
00170   {                                                                     \
00171   public:                                                               \
00172     Class##_StaticInit__()                                              \
00173     {                                                                   \
00174       scfRegisterStaticClass(                                           \
00175         CS_EXPORTED_NAME(Class,_Create), Ident, Desc, Dep);             \
00176     }                                                                   \
00177   } Class##_static_init__;
00178 
00183 #define SCF_REGISTER_STATIC_LIBRARY(Module, MetaInfo)                   \
00184   class Module##_StaticInit                                             \
00185   {                                                                     \
00186   public:                                                               \
00187     Module##_StaticInit()                                               \
00188     {                                                                   \
00189       scfRegisterStaticClasses (MetaInfo);                              \
00190     }                                                                   \
00191   } Module##_static_init__;
00192 
00197 #define SCF_DEFINE_FACTORY_FUNC_REGISTRATION(Class)                     \
00198   CS_EXPORTED_FUNCTION iBase* CS_EXPORTED_NAME(Class,_Create)(iBase*);  \
00199   class Class##_StaticInit                                              \
00200   {                                                                     \
00201   public:                                                               \
00202     Class##_StaticInit()                                                \
00203     {                                                                   \
00204       scfRegisterStaticFactoryFunc (CS_EXPORTED_NAME(Class,_Create),    \
00205         #Class);                                                        \
00206     }                                                                   \
00207   };
00208 
00213 #define SCF_USE_STATIC_PLUGIN(Module)                                   \
00214   namespace csStaticPluginInit                                          \
00215   {                                                                     \
00216     class Module { public: Module(); };                                 \
00217     Module Module##_StaticInit;                                         \
00218   }
00219 
00228 #define SCF_REGISTER_FACTORY_FUNC(Class)                                \
00229   SCF_DEFINE_FACTORY_FUNC_REGISTRATION(Class)                           \
00230   Class##_StaticInit Class##_static_init__;
00231 
00232 //--------------------------------------------- Class factory interface -----//
00233 
00247 struct iFactory : public iBase
00248 {
00250   virtual iBase *CreateInstance () = 0;
00252   virtual void TryUnload () = 0;
00254   virtual const char *QueryDescription () = 0;
00256   virtual const char *QueryDependencies () = 0;
00258   virtual const char *QueryClassID () = 0;
00260   virtual const char *QueryModuleName () = 0;
00261 };
00262 // Give versions to above declared classes.
00263 SCF_VERSION (iFactory, 0, 0, 2);
00264 
00265 //----------------------------------------------- Client-side functions -----//
00266 
00271 enum
00272 {
00273   SCF_VERBOSE_NONE            = 0,      
00274   SCF_VERBOSE_PLUGIN_SCAN     = 1 << 0, 
00275   SCF_VERBOSE_PLUGIN_LOAD     = 1 << 1, 
00276   SCF_VERBOSE_PLUGIN_REGISTER = 1 << 2, 
00277   SCF_VERBOSE_CLASS_REGISTER  = 1 << 3, 
00278   SCF_VERBOSE_ALL             = ~0      
00279 };
00280 
00295 CS_CRYSTALSPACE_EXPORT void scfInitialize(csPathsList const* pluginPaths,
00296   unsigned int verbose = SCF_VERBOSE_NONE);
00297 
00305 CS_CRYSTALSPACE_EXPORT void scfInitialize(int argc, const char* const argv[],
00306   bool scanDefaultPluginPaths = true);
00307 
00309 
00315 CS_CRYSTALSPACE_EXPORT void scfRegisterStaticClass (scfFactoryFunc, 
00316   const char *iClassID, const char *Description, 
00317   const char *Dependencies = 0);
00318 CS_CRYSTALSPACE_EXPORT void scfRegisterStaticClasses (char const* xml);
00319 CS_CRYSTALSPACE_EXPORT void scfRegisterStaticFactoryFunc (scfFactoryFunc, 
00320   const char *FactClass);
00322   
00323 //---------- IMPLEMENTATION OF HELPER FUNCTIONS
00324 
00325 
00329 template<class Interface, class ClassPtr>
00330 inline csPtr<Interface> scfQueryInterface (ClassPtr object)
00331 {
00332   Interface *x = (Interface*)object->QueryInterface (
00333     scfInterfaceTraits<Interface>::GetID (),
00334     scfInterfaceTraits<Interface>::GetVersion ());
00335   return csPtr<Interface> (x);
00336 }
00337 // Save a QI for 'identity' queries 
00338 /*
00339    However, this does not fly on all compilers.
00340    Known working:
00341      gcc 4.1.2
00342    Known NOT working:
00343      gcc 3.4.2
00344  */
00345 #if (!defined(__GNUC__) || (__GNUC__ >= 4))
00346 template<class Interface>
00347 inline csPtr<Interface> scfQueryInterface (Interface* object)
00348 {
00349   object->IncRef ();
00350   return csPtr<Interface> (object);
00351 }
00352 #endif
00353 
00358 template<class Interface, class ClassPtr>
00359 inline csPtr<Interface> scfQueryInterfaceSafe (ClassPtr object)
00360 {
00361   if (object == 0) return csPtr<Interface> (0);
00362   return scfQueryInterface<Interface> (object);
00363 }
00364 
00368 template<class Interface>
00369 inline csPtr<Interface> scfCreateInstance (char const * const ClassID)
00370 {
00371   csRef<iBase> base = csPtr<iBase> (iSCF::SCF->CreateInstance (ClassID));
00372   return scfQueryInterfaceSafe<Interface> (base);
00373 }
00374 
00375 
00376 
00377 // A bit hacky.
00378 #include "csutil/reftrackeraccess.h"
00379 
00382 #endif // __CSSCF_H__

Generated for Crystal Space 2.0 by doxygen 1.7.6.1