## Public API Reference

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

- File List
- File Members

# 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