CrystalSpace

Public API Reference

csutil/scf_interface.h

Go to the documentation of this file.
00001 /*
00002   Crystal Space Shared Class Facility (SCF)
00003   This header contains the parts of SCF that is needed for defining
00004   new interfaces.
00005 
00006   Copyright (C) 1999 by Andrew Zabolotny
00007             (C) 2005 by Marten Svanfeldt
00008             (C) 2005 by Michael Adams
00009 
00010   This library is free software; you can redistribute it and/or
00011   modify it under the terms of the GNU Library General Public
00012   License as published by the Free Software Foundation; either
00013   version 2 of the License, or (at your option) any later version.
00014 
00015   This library is distributed in the hope that it will be useful,
00016   but WITHOUT ANY WARRANTY; without even the implied warranty of
00017   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00018   Library General Public License for more details.
00019 
00020   You should have received a copy of the GNU Library General Public
00021   License along with this library; if not, write to the Free
00022   Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00023 */
00024 
00025 #ifndef __CSUTIL_SCF_INTERFACE_H__
00026 #define __CSUTIL_SCF_INTERFACE_H__
00027 
00028 #include "csextern.h"
00029 
00030 // -- Forward declarations
00031 struct iDocument;
00032 #if defined(CS_DEBUG) || defined(CS_MEMORY_TRACKER)
00033   struct iObjectRegistry;
00034 #endif
00035 template<class T>
00036 class csRef;
00037 struct iStringArray;
00038 
00050 typedef unsigned long scfInterfaceID;
00051 
00055 typedef int scfInterfaceVersion;
00056 
00057 // -- Some helpers needed below
00071 #define SCF_INTERFACE(Name,Major,Minor,Micro)             \
00072 struct InterfaceTraits {                                  \
00073   typedef Name InterfaceType;                             \
00074   CS_FORCEINLINE static scfInterfaceVersion GetVersion() \
00075   { return SCF_CONSTRUCT_VERSION(Major, Minor, Micro); }  \
00076   CS_FORCEINLINE static char const * GetName() { return #Name; }  \
00077 }
00078 
00079 
00081 #define SCF_CONSTRUCT_VERSION(Major,Minor,Micro)          \
00082   ((Major << 24) | (Minor << 16) | Micro)
00083 
00084 
00091 static CS_FORCEINLINE bool scfCompatibleVersion (
00092   scfInterfaceVersion iVersion, scfInterfaceVersion iItfVersion)
00093 {
00094   return (((iVersion & 0xff000000) == (iItfVersion & 0xff000000))
00095      && ((iVersion & 0x00ffffff) <= (iItfVersion & 0x00ffffff)))
00096      || iVersion == 0;
00097 }
00098 
00099 // -- The main two SCF interfaces, iBase and iSCF
00100 
00106 struct iBase
00107 {
00108   // Jorrit: removed the code below as it causes 'pure virtual' method
00109   // calls to happen upon destruction.
00110   //protected:
00113   //virtual ~iBase() {}
00114 public:
00115   SCF_INTERFACE(iBase, 1, 0, 0);
00117   virtual void IncRef () = 0;
00119   virtual void DecRef () = 0;
00121   virtual int GetRefCount () = 0;
00128   virtual void *QueryInterface (scfInterfaceID iInterfaceID, int iVersion) = 0;
00130   virtual void AddRefOwner (iBase** ref_owner) = 0;
00132   virtual void RemoveRefOwner (iBase** ref_owner) = 0;
00133 };
00134 
00136 typedef iBase* (*scfFactoryFunc)(iBase*);
00137 
00144 struct iSCF : public iBase
00145 {
00146   SCF_INTERFACE(iSCF, 2, 0,0);
00158   static CS_CRYSTALSPACE_EXPORT iSCF* SCF;
00159 
00160 #if defined(CS_DEBUG) || defined(CS_MEMORY_TRACKER)
00161   // This is EXTREMELY dirty but I see no other solution for now.
00162   // For debugging reasons I must have a global (global over the application
00163   // and all plugins)pointer to the object registry. I have no other
00164   // global object to tag this pointer on that except for iSCF.
00165   // This pointer is only here in debug mode though. That ensures that it
00166   // cannot be misused in real code.
00167   // If you know another solution for this problem? This global pointer
00168   // will be used by csDebuggingGraph in csutil.
00169   iObjectRegistry* object_reg;
00170 #endif
00171 
00175   virtual void RegisterClasses (iDocument* metadata,
00176     const char* context = 0) = 0;
00177 
00183   virtual void RegisterClasses (char const* xml,
00184     const char* context = 0) = 0;
00185 
00189   virtual void RegisterClasses (const char* pluginPath,
00190     iDocument* metadata, const char* context = 0) = 0;
00191 
00198   virtual bool ClassRegistered (const char *iClassID) = 0;
00199 
00211   virtual iBase *CreateInstance (const char *iClassID) = 0;
00212 
00218   virtual const char *GetClassDescription (const char *iClassID) = 0;
00219 
00225   virtual const char *GetClassDependencies (const char *iClassID) = 0;
00226 
00253   virtual csRef<iDocument> GetPluginMetadata (char const *iClassID) = 0;
00254 
00261   virtual void UnloadUnusedModules () = 0;
00262 
00273   virtual bool RegisterClass (const char *iClassID,
00274     const char *iLibraryName, const char *iFactoryClass,
00275     const char *Description, const char *Dependencies = 0,
00276     const char* context = 0) = 0;
00277 
00284   virtual bool RegisterClass (scfFactoryFunc, const char *iClassID,
00285     const char *Description, const char *Dependencies = 0,
00286     const char* context = 0) = 0;
00287 
00295   virtual bool RegisterFactoryFunc (scfFactoryFunc, const char *FactClass) = 0;
00296 
00303   virtual bool UnregisterClass (const char *iClassID) = 0;
00304 
00309   virtual char const* GetInterfaceName (scfInterfaceID) const = 0;
00310 
00316   virtual scfInterfaceID GetInterfaceID (const char *iInterface) = 0;
00317 
00324   virtual void Finish () = 0;
00325 
00335   virtual csRef<iStringArray> QueryClassList (char const* pattern) = 0;
00336 
00340   virtual void ScanPluginsPath (const char* path, bool recursive = false,
00341     const char* context = 0) = 0;
00342 
00352   virtual bool RegisterPlugin (const char* path) = 0;
00353 };
00354 
00355 
00356 //-- Interface traits
00357 
00367 template <class Interface> 
00368 class scfInterfaceTraits
00369 {
00370 public:
00371   typedef typename_qualifier Interface::InterfaceTraits::InterfaceType 
00372     InterfaceType;
00373 
00377   CS_FORCEINLINE static scfInterfaceVersion GetVersion ()
00378   {
00379     return Interface::InterfaceTraits::GetVersion ();
00380   }
00381 
00389   CS_FORCEINLINE static scfInterfaceID GetID ()
00390   {
00391     scfInterfaceID& ID = GetMyID ();
00392     if (ID == (scfInterfaceID)(-1))
00393     {
00394       ID = iSCF::SCF->GetInterfaceID (GetName ());
00395       csStaticVarCleanup (CleanupID);
00396     }
00397     return ID;
00398   }
00399 
00403   CS_FORCEINLINE static char const* GetName ()
00404   { 
00405     return Interface::InterfaceTraits::GetName ();
00406   }
00407 
00408 private:
00409   // This idiom is a Meyers singleton
00410   CS_FORCEINLINE static scfInterfaceID& GetMyID ()
00411   {
00412     static scfInterfaceID ID = (scfInterfaceID)-1;
00413     return ID;
00414   }
00415   static void CleanupID ()
00416   {
00417     GetMyID () = (scfInterfaceID)-1;
00418   }
00419 };
00420 
00434 #define SCF_VERSION(Name,Major,Minor,Micro)                \
00435 struct Name;                                               \
00436 CS_SPECIALIZE_TEMPLATE                                     \
00437 class scfInterfaceTraits<Name>                             \
00438 {                                                          \
00439 public:                                                    \
00440   typedef Name InterfaceType;                              \
00441   static scfInterfaceVersion GetVersion()                  \
00442   { return SCF_CONSTRUCT_VERSION(Major, Minor, Micro); }   \
00443   static char const* GetName ()                            \
00444   { return #Name; }                                        \
00445   static scfInterfaceID GetID ()                           \
00446   { scfInterfaceID& ID = GetMyID ();                       \
00447     if (ID == (scfInterfaceID)(-1))                        \
00448     { ID = iSCF::SCF->GetInterfaceID (GetName ());         \
00449       csStaticVarCleanup (CleanupID);    }                 \
00450     return ID;                                             \
00451   }                                                        \
00452 private:                                                   \
00453   static scfInterfaceID& GetMyID ()                        \
00454   { static scfInterfaceID ID = (scfInterfaceID)-1; return ID; } \
00455   static void CleanupID ()                                 \
00456   { GetMyID () = (scfInterfaceID)-1; }                     \
00457 }
00458 
00461 #endif
00462 

Generated for Crystal Space by doxygen 1.4.6