Public API Reference

csutil/scf_interface.h

Go to the documentation of this file.

/*
  Crystal Space Shared Class Facility (SCF)
  This header contains the parts of SCF that is needed for defining
  new interfaces.

  Copyright (C) 1999 by Andrew Zabolotny
            (C) 2005 by Marten Svanfeldt
            (C) 2005 by Michael Adams

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Library General Public
  License as published by the Free Software Foundation; either
  version 2 of the License, or (at your option) any later version.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Library General Public License for more details.

  You should have received a copy of the GNU Library General Public
  License along with this library; if not, write to the Free
  Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/

#ifndef __CSUTIL_SCF_INTERFACE_H__
#define __CSUTIL_SCF_INTERFACE_H__

#include "csextern.h"


// -- Forward declarations
struct iDocument;
struct iDocumentNode;
#if defined(CS_DEBUG) || defined(CS_MEMORY_TRACKER)
  struct iObjectRegistry;
#endif
template<class T>
class csRef;
struct iStringArray;

typedef unsigned long scfInterfaceID;

typedef int scfInterfaceVersion;

// -- Some helpers needed below
#define SCF_INTERFACE(Name,Major,Minor,Micro)             \
struct InterfaceTraits {                                  \
  CS_DEPRECATION_WARNINGS_DISABLE                         \
  typedef Name InterfaceType;                             \
  CS_DEPRECATION_WARNINGS_ENABLE                          \
  CS_FORCEINLINE static scfInterfaceVersion GetVersion() \
  { return SCF_CONSTRUCT_VERSION(Major, Minor, Micro); }  \
  CS_FORCEINLINE static char const * GetName() { return #Name; }  \
}


#define SCF_CONSTRUCT_VERSION(Major,Minor,Micro)          \
  ((Major << 24) | (Minor << 16) | Micro)


static CS_FORCEINLINE bool scfCompatibleVersion (
  scfInterfaceVersion iVersion, scfInterfaceVersion iItfVersion)
{
  return (((iVersion & 0xff000000) == (iItfVersion & 0xff000000))
     && ((iVersion & 0x00ffffff) <= (iItfVersion & 0x00ffffff)))
     || iVersion == 0;
}

struct scfInterfaceMetadata
{
  const char* interfaceName;

  scfInterfaceID interfaceID;

  scfInterfaceVersion interfaceVersion;
};

struct scfInterfaceMetadataList
{
  scfInterfaceMetadata* metadata;

  size_t metadataCount;
};

// -- The main two SCF interfaces, iBase and iSCF

struct iBase
{
protected:
  virtual ~iBase() {}
public:
  SCF_INTERFACE(iBase, 1, 1, 0);
  virtual void IncRef () = 0;
  virtual void DecRef () = 0;
  virtual int GetRefCount () = 0;
  virtual void *QueryInterface (scfInterfaceID iInterfaceID, int iVersion) = 0;
  virtual void AddRefOwner (void** ref_owner, CS::Threading::Mutex* mutex) = 0;
  virtual void RemoveRefOwner (void** ref_owner) = 0;
  
  typedef csRef<iBase> WeakReferencedKeepAlive;

  virtual scfInterfaceMetadataList* GetInterfaceMetadata () = 0;
};

typedef iBase* (*scfFactoryFunc)(iBase*);

struct iSCF : public virtual iBase
{
  SCF_INTERFACE(iSCF, 4,0,0);
  static CS_CRYSTALSPACE_EXPORT iSCF* SCF;

#if defined(CS_DEBUG) || defined(CS_MEMORY_TRACKER)
  // This is EXTREMELY dirty but I see no other solution for now.
  // For debugging reasons I must have a global (global over the application
  // and all plugins)pointer to the object registry. I have no other
  // global object to tag this pointer on that except for iSCF.
  // This pointer is only here in debug mode though. That ensures that it
  // cannot be misused in real code.
  // If you know another solution for this problem? This global pointer
  // will be used by csDebuggingGraph in csutil.
  iObjectRegistry* object_reg;
#endif

  virtual void RegisterClasses (iDocument* metadata,
    const char* context = 0) = 0;

  virtual void RegisterClasses (char const* xml,
    const char* context = 0) = 0;

  virtual void RegisterClasses (const char* pluginPath,
    iDocument* metadata, const char* context = 0) = 0;

  virtual bool ClassRegistered (const char *iClassID) = 0;

  virtual iBase *CreateInstance (const char *iClassID) = 0;

  virtual const char *GetClassDescription (const char *iClassID) = 0;

  virtual const char *GetClassDependencies (const char *iClassID) = 0;

  virtual csRef<iDocument> GetPluginMetadata (char const *iClassID) = 0;

  virtual csRef<iDocumentNode> GetPluginMetadataNode (char const *iClassID) = 0;

  virtual void UnloadUnusedModules () = 0;

  virtual bool RegisterClass (const char *iClassID,
    const char *iLibraryName, const char *iFactoryClass,
    const char *Description, const char *Dependencies = 0,
    const char* context = 0) = 0;

  virtual bool RegisterClass (scfFactoryFunc, const char *iClassID,
    const char *Description, const char *Dependencies = 0,
    const char* context = 0) = 0;

  virtual bool RegisterFactoryFunc (scfFactoryFunc, const char *FactClass) = 0;

  virtual bool UnregisterClass (const char *iClassID) = 0;

  virtual char const* GetInterfaceName (scfInterfaceID) const = 0;

  virtual scfInterfaceID GetInterfaceID (const char *iInterface) = 0;

  virtual void Finish () = 0;

  virtual csRef<iStringArray> QueryClassList (char const* pattern) = 0;

  virtual void ScanPluginsPath (const char* path, bool recursive = false,
    const char* context = 0) = 0;

  virtual bool RegisterPlugin (const char* path) = 0;
};


//-- Interface traits

template <typename Interface> 
class scfInterfaceTraits
{
public:
  typedef typename Interface::InterfaceTraits::InterfaceType 
    InterfaceType;

  CS_FORCEINLINE_TEMPLATEMETHOD static scfInterfaceVersion GetVersion ()
  {
    return Interface::InterfaceTraits::GetVersion ();
  }

  CS_FORCEINLINE_TEMPLATEMETHOD static scfInterfaceID GetID ()
  {
    scfInterfaceID& ID = GetMyID ();
    if (ID == (scfInterfaceID)(-1))
    {
      ID = iSCF::SCF->GetInterfaceID (GetName ());
      csStaticVarCleanup (CleanupID);
    }
    return ID;
  }

  CS_FORCEINLINE_TEMPLATEMETHOD static char const* GetName ()
  { 
    return Interface::InterfaceTraits::GetName ();
  }

private:
  // This idiom is a Meyers singleton
  CS_FORCEINLINE_TEMPLATEMETHOD static scfInterfaceID& GetMyID ()
  {
    static scfInterfaceID ID = (scfInterfaceID)-1;
    return ID;
  }
  static void CleanupID ()
  {
    GetMyID () = (scfInterfaceID)-1;
  }
};

#define SCF_VERSION(Name,Major,Minor,Micro)                \
struct Name;                                               \
template<>                                                 \
class scfInterfaceTraits<Name>                             \
{                                                          \
public:                                                    \
  typedef Name InterfaceType;                              \
  static scfInterfaceVersion GetVersion()                  \
  { return SCF_CONSTRUCT_VERSION(Major, Minor, Micro); }   \
  static char const* GetName ()                            \
  { return #Name; }                                        \
  static scfInterfaceID GetID ()                           \
  { scfInterfaceID& ID = GetMyID ();                       \
    if (ID == (scfInterfaceID)(-1))                        \
    { ID = iSCF::SCF->GetInterfaceID (GetName ());         \
      csStaticVarCleanup (CleanupID);    }                 \
    return ID;                                             \
  }                                                        \
private:                                                   \
  static scfInterfaceID& GetMyID ()                        \
  { static scfInterfaceID ID = (scfInterfaceID)-1; return ID; } \
  static void CleanupID ()                                 \
  { GetMyID () = (scfInterfaceID)-1; }                     \
}

#endif

---