csutil/scf.h Source File (Crystal Space 2.0 Public API Reference)

| ## Public API Reference

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

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__