CrystalSpace

Public API Reference

Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

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   static CS_FORCEINLINE scfInterfaceVersion GetVersion()          \
00074   { return SCF_CONSTRUCT_VERSION(Major, Minor, Micro); }  \
00075   static CS_FORCEINLINE char const * GetName() { return #Name; }  \
00076 }
00077 
00078 
00080 #define SCF_CONSTRUCT_VERSION(Major,Minor,Micro)          \
00081   ((Major << 24) | (Minor << 16) | Micro)
00082 
00083 
00090 static CS_FORCEINLINE bool scfCompatibleVersion (
00091   scfInterfaceVersion iVersion, scfInterfaceVersion iItfVersion)
00092 {
00093   return (((iVersion & 0xff000000) == (iItfVersion & 0xff000000))
00094      && ((iVersion & 0x00ffffff) <= (iItfVersion & 0x00ffffff))) || iVersion == 0;
00095 }
00096 
00097 // -- The main two SCF interfaces, iBase and iSCF
00098 
00104 struct iBase
00105 {
00106   // Jorrit: removed the code below as it causes 'pure virtual' method
00107   // calls to happen upon destruction.
00108   //protected:
00111   //virtual ~iBase() {}
00112 public:
00113   SCF_INTERFACE(iBase, 1, 0, 0);
00115   virtual void IncRef () = 0;
00117   virtual void DecRef () = 0;
00119   virtual int GetRefCount () = 0;
00126   virtual void *QueryInterface (scfInterfaceID iInterfaceID, int iVersion) = 0;
00128   virtual void AddRefOwner (iBase** ref_owner) = 0;
00130   virtual void RemoveRefOwner (iBase** ref_owner) = 0;
00131 };
00132 
00134 typedef iBase* (*scfFactoryFunc)(iBase*);
00135 
00142 struct iSCF : public iBase
00143 {
00144   SCF_INTERFACE(iSCF, 2, 0,0);
00156   static CS_CRYSTALSPACE_EXPORT iSCF* SCF;
00157 
00158 #if defined(CS_DEBUG) || defined(CS_MEMORY_TRACKER)
00159   // This is EXTREMELY dirty but I see no other solution for now.
00160   // For debugging reasons I must have a global (global over the application
00161   // and all plugins)pointer to the object registry. I have no other
00162   // global object to tag this pointer on that except for iSCF.
00163   // This pointer is only here in debug mode though. That ensures that it
00164   // cannot be misused in real code.
00165   // If you know another solution for this problem? This global pointer
00166   // will be used by csDebuggingGraph in csutil.
00167   iObjectRegistry* object_reg;
00168 #endif
00169 
00173   virtual void RegisterClasses (iDocument* metadata,
00174     const char* context = 0) = 0;
00175 
00181   virtual void RegisterClasses (char const* xml,
00182     const char* context = 0) = 0;
00183 
00187   virtual void RegisterClasses (const char* pluginPath,
00188     iDocument* metadata, const char* context = 0) = 0;
00189 
00196   virtual bool ClassRegistered (const char *iClassID) = 0;
00197 
00209   virtual iBase *CreateInstance (const char *iClassID) = 0;
00210 
00216   virtual const char *GetClassDescription (const char *iClassID) = 0;
00217 
00223   virtual const char *GetClassDependencies (const char *iClassID) = 0;
00224 
00251   virtual csRef<iDocument> GetPluginMetadata (char const *iClassID) = 0;
00252 
00259   virtual void UnloadUnusedModules () = 0;
00260 
00271   virtual bool RegisterClass (const char *iClassID,
00272     const char *iLibraryName, const char *iFactoryClass,
00273     const char *Description, const char *Dependencies = 0,
00274     const char* context = 0) = 0;
00275 
00282   virtual bool RegisterClass (scfFactoryFunc, const char *iClassID,
00283     const char *Description, const char *Dependencies = 0,
00284     const char* context = 0) = 0;
00285 
00293   virtual bool RegisterFactoryFunc (scfFactoryFunc, const char *FactClass) = 0;
00294 
00301   virtual bool UnregisterClass (const char *iClassID) = 0;
00302 
00307   virtual char const* GetInterfaceName (scfInterfaceID) const = 0;
00308 
00314   virtual scfInterfaceID GetInterfaceID (const char *iInterface) = 0;
00315 
00322   virtual void Finish () = 0;
00323 
00333   virtual csRef<iStringArray> QueryClassList (char const* pattern) = 0;
00334 
00338   virtual void ScanPluginsPath (const char* path, bool recursive = false,
00339     const char* context = 0) = 0;
00340 
00350   virtual bool RegisterPlugin (const char* path) = 0;
00351 };
00352 
00353 
00354 //-- Interface traits
00355 
00365 template <class Interface> 
00366 class scfInterfaceTraits
00367 {
00368 public:
00372   static scfInterfaceVersion GetVersion ()
00373   {
00374     return Interface::InterfaceTraits::GetVersion ();
00375   }
00376 
00384   static scfInterfaceID GetID ()
00385   {
00386     scfInterfaceID& ID = GetMyID ();
00387     if (ID == (scfInterfaceID)(-1))
00388     {
00389       ID = iSCF::SCF->GetInterfaceID (GetName ());
00390       csStaticVarCleanup (CleanupID);
00391     }
00392     return ID;
00393   }
00394 
00398   static CS_FORCEINLINE char const* GetName ()
00399   { 
00400     return Interface::InterfaceTraits::GetName ();
00401   }
00402 private:
00403   // This idiom is a Meyers singleton
00404   static CS_FORCEINLINE scfInterfaceID& GetMyID ()
00405   {
00406     static scfInterfaceID ID = (scfInterfaceID)-1;
00407     return ID;
00408   }
00409   static void CleanupID ()
00410   {
00411     GetMyID () = (scfInterfaceID)-1;
00412   }
00413 };
00414 
00428 #define SCF_VERSION(Name,Major,Minor,Micro)                \
00429 struct Name;                                               \
00430 CS_SPECIALIZE_TEMPLATE                                     \
00431 class scfInterfaceTraits<Name>                             \
00432 {                                                          \
00433 public:                                                    \
00434   static scfInterfaceVersion GetVersion()                  \
00435   { return SCF_CONSTRUCT_VERSION(Major, Minor, Micro); }   \
00436   static char const* GetName ()                            \
00437   { return #Name; }                                        \
00438   static scfInterfaceID GetID ()                           \
00439   { scfInterfaceID& ID = GetMyID ();                       \
00440     if (ID == (scfInterfaceID)(-1))                        \
00441     { ID = iSCF::SCF->GetInterfaceID (GetName ());         \
00442       csStaticVarCleanup (CleanupID);    }                 \
00443     return ID;                                             \
00444   }                                                        \
00445 private:                                                   \
00446   static scfInterfaceID& GetMyID ()                        \
00447   { static scfInterfaceID ID = (scfInterfaceID)-1; return ID; } \
00448   static void CleanupID ()                                 \
00449   { GetMyID () = (scfInterfaceID)-1; }                     \
00450 }
00451 
00454 #endif
00455 

Generated for Crystal Space by doxygen 1.4.4