CrystalSpace

Public API Reference

iutil/plugin.h
Go to the documentation of this file.
00001 /*
00002     Copyright (C) 2001,2006 by Jorrit Tyberghein
00003     Copyright (C) 1999 by Andrew Zabolotny <bit@eltech.ru>
00004 
00005     This library is free software; you can redistribute it and/or
00006     modify it under the terms of the GNU Library General Public
00007     License as published by the Free Software Foundation; either
00008     version 2 of the License, or (at your option) any later version.
00009 
00010     This library is distributed in the hope that it will be useful,
00011     but WITHOUT ANY WARRANTY; without even the implied warranty of
00012     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013     Library General Public License for more details.
00014 
00015     You should have received a copy of the GNU Library General Public
00016     License along with this library; if not, write to the Free
00017     Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00018 */
00019 
00020 #ifndef __CS_IUTIL_PLUGIN_H__
00021 #define __CS_IUTIL_PLUGIN_H__
00022 
00032 #include "csutil/scf.h"
00033 #include "csutil/stringquote.h"
00034 #include "iutil/comp.h"
00035 #include "iutil/objreg.h"
00036 #include "iutil/threadmanager.h"
00037 #include "ivaria/reporter.h"
00038 
00042 struct iPluginIterator : public virtual iBase
00043 {
00044   SCF_INTERFACE(iPluginIterator, 3,0,0);
00046   virtual bool HasNext () = 0;
00048   virtual iComponent* Next () = 0;
00049 };
00050 
00062 struct iPluginManager : public virtual iBase
00063 {
00064   SCF_INTERFACE(iPluginManager, 4, 0, 1);
00065   
00070   enum
00071   {
00073     lpiInitialize = 1,
00075     lpiReportErrors = 2,
00077     lpiLoadDependencies = 4,
00079     lpiReturnLoadedInstance = 8
00080   };
00081   
00100   virtual csPtr<iComponent> LoadPluginInstance (const char *classID,
00101                                                 uint loadFlags) = 0;
00102   // Deprecated in 2.0
00103   CS_DEPRECATED_METHOD_MSG("Use LoadPluginInstance()")
00104   inline iBase* LoadPlugin (const char *classID, bool init = true, bool report = true)
00105   {
00106     uint flags = 0;
00107     if (init) flags |= lpiInitialize;
00108     if (report) flags |= lpiReportErrors;
00109     csRef<iComponent> comp (LoadPluginInstance (classID, flags));
00110     if (comp) comp->IncRef();
00111     return (iBase*)comp;
00112   }
00113 
00123   virtual csPtr<iComponent> QueryPluginInstance (const char *iInterface,
00124                                                  int iVersion) = 0;
00125   // Deprecated in 2.0
00126   CS_DEPRECATED_METHOD_MSG("Use QueryPluginInstance()")
00127   inline iBase* QueryPlugin (const char *iInterface, int iVersion)
00128   {
00129     csRef<iComponent> comp (QueryPluginInstance (iInterface, iVersion));
00130     if (comp) comp->IncRef();
00131     return (iBase*)comp;
00132   }
00133   
00135 
00141   virtual csPtr<iComponent> QueryPluginInstance (const char* classID) = 0;
00142   virtual csPtr<iComponent> QueryPluginInstance (const char* classID,
00143         const char *iInterface, int iVersion) = 0;
00145   // Deprecated in 2.0
00146   CS_DEPRECATED_METHOD_MSG("Use QueryPluginInstance()")
00147   inline iBase* QueryPlugin (const char* classID,
00148         const char *iInterface, int iVersion)
00149   {
00150     csRef<iComponent> comp (QueryPluginInstance (classID, iInterface, iVersion));
00151     if (comp) comp->IncRef();
00152     return (iBase*)comp;
00153   }
00154   
00156   virtual bool UnloadPluginInstance (iComponent *obj) = 0;
00157   // Deprecated in 2.0
00158   CS_DEPRECATED_METHOD_MSG("Use UnloadPluginInstance()")
00159   inline bool UnloadPlugin (iComponent *obj)
00160   { return UnloadPluginInstance (obj); }
00161   
00163   virtual bool RegisterPluginInstance (const char *classID, iComponent *obj) = 0;
00164   // Deprecated in 2.0
00165   CS_DEPRECATED_METHOD_MSG("Use RegisterPluginInstance()")
00166   inline bool RegisterPlugin (const char *classID, iComponent *obj)
00167   { return RegisterPluginInstance (classID, obj); }
00168 
00174   virtual csPtr<iPluginIterator> GetPluginInstances () = 0;
00175   // Deprecated in 2.0
00176   CS_DEPRECATED_METHOD_MSG("Use GetPluginInstances()")
00177   inline csPtr<iPluginIterator> GetPlugins ()
00178   { return GetPluginInstances (); }
00180   virtual void Clear () = 0;
00181 
00189   virtual void QueryOptions (iComponent* object) = 0;
00190   
00195   virtual bool SetTagClassIDMapping (const char* tag, const char* classID) = 0;
00197   virtual bool UnsetTagClassIDMapping (const char* tag) = 0;
00199   virtual const char* GetTagClassIDMapping (const char* tag) = 0;
00205   virtual csPtr<iStringArray> GetClassIDTags (const char* classID) = 0;
00211   virtual csPtr<iComponent> LoadTagPluginInstance (const char* tag,
00212     uint loadFlags) = 0;
00217   virtual csPtr<iComponent> QueryTagPluginInstance (const char* tag) = 0;
00218   
00219 };
00220 
00221 
00230 template<class Interface>
00231 inline csPtr<Interface> csQueryPluginClass (iPluginManager *mgr,
00232                                             const char* ClassID)
00233 {
00234   csRef<iComponent> base = mgr->QueryPluginInstance (ClassID,
00235     scfInterfaceTraits<Interface>::GetName(),
00236     scfInterfaceTraits<Interface>::GetVersion());
00237   return scfQueryInterfaceSafe<Interface> (base);
00238 }
00239 
00244 #define CS_QUERY_PLUGIN_CLASS(Object,ClassID,Interface)                 \
00245   csQueryPluginClass<Interface> (Object, ClassID)
00246 
00253 template<class Interface>
00254 inline csPtr<Interface> csLoadPlugin (iPluginManager *mgr,
00255                                       const char* ClassID,
00256                                       bool report = true,
00257                                       bool returnLoadedInstance = false)
00258 {
00259   csRef<iComponent> base;
00260   uint flags = iPluginManager::lpiInitialize | iPluginManager::lpiLoadDependencies;
00261   if (report) flags |= iPluginManager::lpiReportErrors;
00262   if (returnLoadedInstance) flags |= iPluginManager::lpiReturnLoadedInstance;
00263   base = mgr->LoadPluginInstance (ClassID, flags);
00264   return scfQueryInterfaceSafe<Interface> (base);
00265 }
00266 
00273 template<class Interface>
00274 inline csPtr<Interface> csLoadPlugin (iObjectRegistry* object_reg,
00275                                       const char* ClassID,
00276                                       bool report = true)
00277 {
00278   csRef<iPluginManager> mgr = csQueryRegistry<iPluginManager> (object_reg);
00279   if (!mgr) return 0;
00280   return csLoadPlugin<Interface> (mgr, ClassID, report);
00281 }
00282 
00290 template<class Interface>
00291 inline csPtr<Interface> csLoadPluginCheck (iPluginManager *mgr,
00292                                            const char* ClassID,
00293                                            bool report = true)
00294 {
00295   csRef<Interface> i = csQueryPluginClass<Interface> (mgr, ClassID);
00296   if (i) return (csPtr<Interface>) i;
00297   i = csLoadPlugin<Interface> (mgr, ClassID, report, true);
00298   if (!i) return 0;
00299   return (csPtr<Interface>) i;
00300 }
00301 
00310 template<class Interface>
00311 inline csPtr<Interface> csLoadPluginCheck (iObjectRegistry* object_reg,
00312                                       const char* ClassID, bool report = true)
00313 {
00314   csRef<iPluginManager> mgr = csQueryRegistry<iPluginManager> (object_reg);
00315   if (!mgr)
00316   {
00317     if (report)
00318       csReport (object_reg, CS_REPORTER_SEVERITY_ERROR,
00319         "crystalspace.plugin.load", "Couldn't find plugin manager!");
00320     return 0;
00321   }
00322   csRef<Interface> i = csLoadPluginCheck<Interface> (mgr, ClassID, report);
00323   if (!i)
00324   {
00325     if (report)
00326       csReport (object_reg, CS_REPORTER_SEVERITY_ERROR,
00327         "crystalspace.plugin.load", "Couldn't load plugin with class %s!",
00328                 CS::Quote::Single (ClassID));
00329     return 0;
00330   }
00331   return (csPtr<Interface>) i;
00332 }
00333 
00338 inline csPtr<iComponent> csLoadPluginAlways (iPluginManager *mgr,
00339                                              const char* ClassID,
00340                                              bool report = true)
00341 {
00342   uint flags =
00343     iPluginManager::lpiInitialize | iPluginManager::lpiLoadDependencies;
00344   if (report) flags |= iPluginManager::lpiReportErrors;
00345   return mgr->LoadPluginInstance (ClassID, flags);
00346 }
00347 
00369 template<class Interface>
00370 inline csPtr<Interface> csQueryRegistryOrLoad (iObjectRegistry *Reg,
00371         const char* classID, bool report = true)
00372 {
00373   csRef<Interface> i = csQueryRegistry<Interface> (Reg);
00374   if (i) return (csPtr<Interface>)i;
00375   csRef<iPluginManager> plugmgr = csQueryRegistry<iPluginManager> (Reg);
00376   if (!plugmgr)
00377   {
00378     if (report)
00379       csReport (Reg, CS_REPORTER_SEVERITY_ERROR,
00380         "crystalspace.plugin.query", "Plugin manager missing!");
00381     return 0;
00382   }
00383   i = csLoadPlugin<Interface> (plugmgr, classID, report);
00384   if (!i)
00385   {
00386     if (report)
00387       csReport (Reg, CS_REPORTER_SEVERITY_ERROR,
00388         "crystalspace.plugin.query",
00389         "Couldn't load plugin with class %s!", CS::Quote::Single (classID));
00390     return 0;
00391   }
00392   if (!Reg->Register (i, scfInterfaceTraits<Interface>::GetName ()))
00393   {
00394     if (report)
00395       csReport (Reg, CS_REPORTER_SEVERITY_ERROR,
00396         "crystalspace.plugin.query",
00397         "Couldn't register plugin with class %s!", CS::Quote::Single (classID));
00398     return 0;
00399   }
00400   return (csPtr<Interface>)i;
00401 }
00402 
00405 #endif // __CS_IUTIL_PLUGIN_H__

Generated for Crystal Space 2.0 by doxygen 1.7.6.1