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 
00031 // -- Forward declarations
00032 struct iDocument;
00033 #if defined(CS_DEBUG) || defined(CS_MEMORY_TRACKER)
00034   struct iObjectRegistry;
00035 #endif
00036 template<class T>
00037 class csRef;
00038 struct iStringArray;
00039 
00051 typedef unsigned long scfInterfaceID;
00052 
00056 typedef int scfInterfaceVersion;
00057 
00058 // -- Some helpers needed below
00072 #define SCF_INTERFACE(Name,Major,Minor,Micro)             \
00073 struct InterfaceTraits {                                  \
00074   typedef Name InterfaceType;                             \
00075   CS_FORCEINLINE static scfInterfaceVersion GetVersion() \
00076   { return SCF_CONSTRUCT_VERSION(Major, Minor, Micro); }  \
00077   CS_FORCEINLINE static char const * GetName() { return #Name; }  \
00078 }
00079 
00080 
00082 #define SCF_CONSTRUCT_VERSION(Major,Minor,Micro)          \
00083   ((Major << 24) | (Minor << 16) | Micro)
00084 
00085 
00092 static CS_FORCEINLINE bool scfCompatibleVersion (
00093   scfInterfaceVersion iVersion, scfInterfaceVersion iItfVersion)
00094 {
00095   return (((iVersion & 0xff000000) == (iItfVersion & 0xff000000))
00096      && ((iVersion & 0x00ffffff) <= (iItfVersion & 0x00ffffff)))
00097      || iVersion == 0;
00098 }
00099 
00100 // -- The main two SCF interfaces, iBase and iSCF
00101 
00107 struct iBase
00108 {
00109 protected:
00114   virtual ~iBase() {}
00115 public:
00116   SCF_INTERFACE(iBase, 1, 0, 0);
00118   virtual void IncRef () = 0;
00120   virtual void DecRef () = 0;
00122   virtual int GetRefCount () = 0;
00129   virtual void *QueryInterface (scfInterfaceID iInterfaceID, int iVersion) = 0;
00131   virtual void AddRefOwner (void** ref_owner) = 0;
00133   virtual void RemoveRefOwner (void** ref_owner) = 0;
00134 };
00135 
00137 typedef iBase* (*scfFactoryFunc)(iBase*);
00138 
00145 struct iSCF : public virtual iBase
00146 {
00147   SCF_INTERFACE(iSCF, 3,0,0);
00159   static CS_CRYSTALSPACE_EXPORT iSCF* SCF;
00160 
00161 #if defined(CS_DEBUG) || defined(CS_MEMORY_TRACKER)
00162   // This is EXTREMELY dirty but I see no other solution for now.
00163   // For debugging reasons I must have a global (global over the application
00164   // and all plugins)pointer to the object registry. I have no other
00165   // global object to tag this pointer on that except for iSCF.
00166   // This pointer is only here in debug mode though. That ensures that it
00167   // cannot be misused in real code.
00168   // If you know another solution for this problem? This global pointer
00169   // will be used by csDebuggingGraph in csutil.
00170   iObjectRegistry* object_reg;
00171 #endif
00172 
00176   virtual void RegisterClasses (iDocument* metadata,
00177     const char* context = 0) = 0;
00178 
00184   virtual void RegisterClasses (char const* xml,
00185     const char* context = 0) = 0;
00186 
00190   virtual void RegisterClasses (const char* pluginPath,
00191     iDocument* metadata, const char* context = 0) = 0;
00192 
00199   virtual bool ClassRegistered (const char *iClassID) = 0;
00200 
00212   virtual iBase *CreateInstance (const char *iClassID) = 0;
00213 
00219   virtual const char *GetClassDescription (const char *iClassID) = 0;
00220 
00226   virtual const char *GetClassDependencies (const char *iClassID) = 0;
00227 
00254   virtual csRef<iDocument> GetPluginMetadata (char const *iClassID) = 0;
00255 
00262   virtual void UnloadUnusedModules () = 0;
00263 
00274   virtual bool RegisterClass (const char *iClassID,
00275     const char *iLibraryName, const char *iFactoryClass,
00276     const char *Description, const char *Dependencies = 0,
00277     const char* context = 0) = 0;
00278 
00285   virtual bool RegisterClass (scfFactoryFunc, const char *iClassID,
00286     const char *Description, const char *Dependencies = 0,
00287     const char* context = 0) = 0;
00288 
00296   virtual bool RegisterFactoryFunc (scfFactoryFunc, const char *FactClass) = 0;
00297 
00304   virtual bool UnregisterClass (const char *iClassID) = 0;
00305 
00310   virtual char const* GetInterfaceName (scfInterfaceID) const = 0;
00311 
00317   virtual scfInterfaceID GetInterfaceID (const char *iInterface) = 0;
00318 
00325   virtual void Finish () = 0;
00326 
00336   virtual csRef<iStringArray> QueryClassList (char const* pattern) = 0;
00337 
00341   virtual void ScanPluginsPath (const char* path, bool recursive = false,
00342     const char* context = 0) = 0;
00343 
00353   virtual bool RegisterPlugin (const char* path) = 0;
00354 };
00355 
00356 
00357 //-- Interface traits
00358 
00368 template <typename Interface> 
00369 class scfInterfaceTraits
00370 {
00371 public:
00372   typedef typename Interface::InterfaceTraits::InterfaceType 
00373     InterfaceType;
00374 
00378   CS_FORCEINLINE_TEMPLATEMETHOD static scfInterfaceVersion GetVersion ()
00379   {
00380     return Interface::InterfaceTraits::GetVersion ();
00381   }
00382 
00390   CS_FORCEINLINE_TEMPLATEMETHOD static scfInterfaceID GetID ()
00391   {
00392     scfInterfaceID& ID = GetMyID ();
00393     if (ID == (scfInterfaceID)(-1))
00394     {
00395       ID = iSCF::SCF->GetInterfaceID (GetName ());
00396       csStaticVarCleanup (CleanupID);
00397     }
00398     return ID;
00399   }
00400 
00404   CS_FORCEINLINE_TEMPLATEMETHOD static char const* GetName ()
00405   { 
00406     return Interface::InterfaceTraits::GetName ();
00407   }
00408 
00409 private:
00410   // This idiom is a Meyers singleton
00411   CS_FORCEINLINE_TEMPLATEMETHOD static scfInterfaceID& GetMyID ()
00412   {
00413     static scfInterfaceID ID = (scfInterfaceID)-1;
00414     return ID;
00415   }
00416   static void CleanupID ()
00417   {
00418     GetMyID () = (scfInterfaceID)-1;
00419   }
00420 };
00421 
00435 #define SCF_VERSION(Name,Major,Minor,Micro)                \
00436 struct Name;                                               \
00437 template<>                                                 \
00438 class scfInterfaceTraits<Name>                             \
00439 {                                                          \
00440 public:                                                    \
00441   typedef Name InterfaceType;                              \
00442   static scfInterfaceVersion GetVersion()                  \
00443   { return SCF_CONSTRUCT_VERSION(Major, Minor, Micro); }   \
00444   static char const* GetName ()                            \
00445   { return #Name; }                                        \
00446   static scfInterfaceID GetID ()                           \
00447   { scfInterfaceID& ID = GetMyID ();                       \
00448     if (ID == (scfInterfaceID)(-1))                        \
00449     { ID = iSCF::SCF->GetInterfaceID (GetName ());         \
00450       csStaticVarCleanup (CleanupID);    }                 \
00451     return ID;                                             \
00452   }                                                        \
00453 private:                                                   \
00454   static scfInterfaceID& GetMyID ()                        \
00455   { static scfInterfaceID ID = (scfInterfaceID)-1; return ID; } \
00456   static void CleanupID ()                                 \
00457   { GetMyID () = (scfInterfaceID)-1; }                     \
00458 }
00459 
00462 #endif
00463 

Generated for Crystal Space 1.2.1 by doxygen 1.5.3