00001 /** 00002 * vim: set ts=4 : 00003 * ============================================================================= 00004 * SourceMod 00005 * Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved. 00006 * ============================================================================= 00007 * 00008 * This program is free software; you can redistribute it and/or modify it under 00009 * the terms of the GNU General Public License, version 3.0, as published by the 00010 * Free Software Foundation. 00011 * 00012 * This program is distributed in the hope that it will be useful, but WITHOUT 00013 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00014 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 00015 * details. 00016 * 00017 * You should have received a copy of the GNU General Public License along with 00018 * this program. If not, see <http://www.gnu.org/licenses/>. 00019 * 00020 * As a special exception, AlliedModders LLC gives you permission to link the 00021 * code of this program (as well as its derivative works) to "Half-Life 2," the 00022 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software 00023 * by the Valve Corporation. You must obey the GNU General Public License in 00024 * all respects for all other code used. Additionally, AlliedModders LLC grants 00025 * this exception to all derivative works. AlliedModders LLC defines further 00026 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007), 00027 * or <http://www.sourcemod.net/license.php>. 00028 * 00029 * Version: $Id: IPluginSys.h 2459 2008-08-15 05:22:26Z dvander $ 00030 */ 00031 00032 #ifndef _INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_ 00033 #define _INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_ 00034 00035 /** 00036 * @file IPluginSys.h 00037 * @brief Defines the interface for the Plugin System, which manages loaded plugins. 00038 */ 00039 00040 #include <IShareSys.h> 00041 #include <sp_vm_api.h> 00042 00043 #define SMINTERFACE_PLUGINSYSTEM_NAME "IPluginManager" 00044 #define SMINTERFACE_PLUGINSYSTEM_VERSION 2 00045 00046 /** Context user slot 3 is used Core for holding an IPluginContext pointer. */ 00047 #define SM_CONTEXTVAR_USER 3 00048 00049 namespace SourceMod 00050 { 00051 class IPlugin; 00052 00053 /** 00054 * @brief Encapsulates plugin public information exposed through "myinfo." 00055 */ 00056 typedef struct sm_plugininfo_s 00057 { 00058 const char *name; /**< Plugin name */ 00059 const char *author; /**< Plugin author */ 00060 const char *description; /**< Plugin description */ 00061 const char *version; /**< Plugin version string */ 00062 const char *url; /**< Plugin URL */ 00063 } sm_plugininfo_t; 00064 00065 00066 /** 00067 * @brief Describes the usability status of a plugin. 00068 */ 00069 enum PluginStatus 00070 { 00071 Plugin_Running=0, /**< Plugin is running */ 00072 /* All states below are unexecutable */ 00073 Plugin_Paused, /**< Plugin is loaded but paused */ 00074 Plugin_Error, /**< Plugin is loaded but errored/locked */ 00075 /* All states below do not have all natives */ 00076 Plugin_Loaded, /**< Plugin has passed loading and can be finalized */ 00077 Plugin_Failed, /**< Plugin has a fatal failure */ 00078 Plugin_Created, /**< Plugin is created but not initialized */ 00079 Plugin_Uncompiled, /**< Plugin is not yet compiled by the JIT */ 00080 Plugin_BadLoad, /**< Plugin failed to load */ 00081 }; 00082 00083 00084 /** 00085 * @brief Describes the object lifetime of a plugin. 00086 */ 00087 enum PluginType 00088 { 00089 PluginType_Private, /**< Plugin is privately managed and receives no forwards */ 00090 PluginType_MapUpdated, /**< Plugin will never be unloaded unless for updates on mapchange */ 00091 PluginType_MapOnly, /**< Plugin will be removed at mapchange */ 00092 PluginType_Global, /**< Plugin will never be unloaded or updated */ 00093 }; 00094 00095 /** 00096 * @brief Encapsulates a run-time plugin as maintained by SourceMod. 00097 */ 00098 class IPlugin 00099 { 00100 public: 00101 /** Virtual destructor */ 00102 virtual ~IPlugin() 00103 { 00104 } 00105 00106 /** 00107 * @brief Returns the lifetime of a plugin. 00108 */ 00109 virtual PluginType GetType() =0; 00110 00111 /** 00112 * @brief Returns the IPluginRuntime::GetDefaultContext() value. 00113 * 00114 * @return Pointer to an IPluginContext, or NULL if not loaded. 00115 */ 00116 virtual SourcePawn::IPluginContext *GetBaseContext() =0; 00117 00118 /** 00119 * @brief Deprecated, returns NULL. 00120 * 00121 * @return NULL. 00122 */ 00123 virtual sp_context_t *GetContext() =0; 00124 00125 /** 00126 * @brief Deprecated, returns NULL. 00127 * 00128 * @return NULL. 00129 */ 00130 virtual void *GetPluginStructure() =0; 00131 00132 /** 00133 * @brief Returns information about the plugin by reference. 00134 * 00135 * @return Pointer to a sm_plugininfo_t object, NULL if plugin is not loaded. 00136 */ 00137 virtual const sm_plugininfo_t *GetPublicInfo() =0; 00138 00139 /** 00140 * @brief Returns the plugin filename (relative to plugins dir). 00141 */ 00142 virtual const char *GetFilename() =0; 00143 00144 /** 00145 * @brief Returns true if a plugin is in debug mode, false otherwise. 00146 */ 00147 virtual bool IsDebugging() =0; 00148 00149 /** 00150 * @brief Returns the plugin status. 00151 */ 00152 virtual PluginStatus GetStatus() =0; 00153 00154 /** 00155 * @brief Sets whether the plugin is paused or not. 00156 * 00157 * @return True on successful state change, false otherwise. 00158 */ 00159 virtual bool SetPauseState(bool paused) =0; 00160 00161 /** 00162 * @brief Returns the unique serial number of a plugin. 00163 */ 00164 virtual unsigned int GetSerial() =0; 00165 00166 /** 00167 * @brief Returns a plugin's identity token. 00168 */ 00169 virtual IdentityToken_t *GetIdentity() =0; 00170 00171 /** 00172 * @brief Sets a property on this plugin. This is used for per-plugin 00173 * data from extensions or other parts of core. The property's value must 00174 * be manually destructed when the plugin is destroyed. 00175 * 00176 * @param prop String containing name of the property. 00177 * @param ptr Generic pointer to set. 00178 * @return True on success, false if the property is already set. 00179 */ 00180 virtual bool SetProperty(const char *prop, void *ptr) =0; 00181 00182 /** 00183 * @brief Gets a property from a plugin. 00184 * 00185 * @param prop String containing the property's name. 00186 * @param ptr Optional pointer to the generic pointer. 00187 * @param remove Optional boolean value; if true, property is removed 00188 * (so it can be set again). 00189 * @return True if the property existed, false otherwise. 00190 */ 00191 virtual bool GetProperty(const char *prop, void **ptr, bool remove=false) =0; 00192 00193 /** 00194 * @brief Returns the runtime representing this plugin. 00195 * 00196 * @return IPluginRuntime pointer, or NULL if not loaded. 00197 */ 00198 virtual SourcePawn::IPluginRuntime *GetRuntime() =0; 00199 }; 00200 00201 00202 /** 00203 * @brief Iterates over a list of plugins. 00204 */ 00205 class IPluginIterator 00206 { 00207 public: 00208 /** Virtual destructor */ 00209 virtual ~IPluginIterator() 00210 { 00211 }; 00212 public: 00213 /** 00214 * @brief Returns true if there are more plugins in the iterator. 00215 */ 00216 virtual bool MorePlugins() =0; 00217 00218 /** 00219 * @brief Returns the plugin at the current iterator position. 00220 */ 00221 virtual IPlugin *GetPlugin() =0; 00222 00223 /** 00224 * @brief Advances to the next plugin in the iterator. 00225 */ 00226 virtual void NextPlugin() =0; 00227 00228 /** 00229 * @brief Destroys the iterator object. 00230 * Note: You may use 'delete' in lieu of this function. 00231 */ 00232 virtual void Release() =0; 00233 }; 00234 00235 /** 00236 * @brief Listens for plugin-oriented events. 00237 */ 00238 class IPluginsListener 00239 { 00240 public: 00241 /** 00242 * @brief Called when a plugin is created/mapped into memory. 00243 */ 00244 virtual void OnPluginCreated(IPlugin *plugin) 00245 { 00246 } 00247 00248 /** 00249 * @brief Called when a plugin is fully loaded successfully. 00250 */ 00251 virtual void OnPluginLoaded(IPlugin *plugin) 00252 { 00253 } 00254 00255 /** 00256 * @brief Called when a plugin is paused or unpaused. 00257 */ 00258 virtual void OnPluginPauseChange(IPlugin *plugin, bool paused) 00259 { 00260 } 00261 00262 /** 00263 * @brief Called when a plugin is unloaded (only if fully loaded). 00264 */ 00265 virtual void OnPluginUnloaded(IPlugin *plugin) 00266 { 00267 } 00268 00269 /** 00270 * @brief Called when a plugin is destroyed. 00271 * NOTE: Always called if Created, even if load failed. 00272 */ 00273 virtual void OnPluginDestroyed(IPlugin *plugin) 00274 { 00275 } 00276 }; 00277 00278 00279 /** 00280 * @brief Manages the runtime loading and unloading of plugins. 00281 */ 00282 class IPluginManager : public SMInterface 00283 { 00284 public: 00285 virtual const char *GetInterfaceName() 00286 { 00287 return SMINTERFACE_PLUGINSYSTEM_NAME; 00288 } 00289 00290 virtual unsigned int GetInterfaceVersion() 00291 { 00292 return SMINTERFACE_PLUGINSYSTEM_VERSION; 00293 } 00294 public: 00295 /** 00296 * @brief Attempts to load a plugin. 00297 * 00298 * @param path Path and filename of plugin, relative to plugins folder. 00299 * @param debug Deprecated, must be false. 00300 * @param type Lifetime of the plugin. 00301 * @param error Buffer to hold any error message. 00302 * @param maxlength Maximum length of error message buffer. 00303 * @param wasloaded Stores if the plugin is already loaded. 00304 * @return A new plugin pointer on success, false otherwise. 00305 */ 00306 virtual IPlugin *LoadPlugin(const char *path, 00307 bool debug, 00308 PluginType type, 00309 char error[], 00310 size_t maxlength, 00311 bool *wasloaded) =0; 00312 00313 /** 00314 * @brief Attempts to unload a plugin. 00315 * 00316 * @param plugin Pointer to the plugin handle. 00317 * @return True on success, false otherwise. 00318 */ 00319 virtual bool UnloadPlugin(IPlugin *plugin) =0; 00320 00321 /** 00322 * @brief Finds a plugin by its context. 00323 * Note: This function should be considered O(1). 00324 * 00325 * @param ctx Pointer to an sp_context_t. 00326 * @return Pointer to a matching IPlugin, or NULL if none found. 00327 */ 00328 virtual IPlugin *FindPluginByContext(const sp_context_t *ctx) =0; 00329 00330 /** 00331 * @brief Returns the number of plugins (both failed and loaded). 00332 * 00333 * @return The number of internally cached plugins. 00334 */ 00335 virtual unsigned int GetPluginCount() =0; 00336 00337 /** 00338 * @brief Returns a pointer that can be used to iterate through plugins. 00339 * Note: This pointer must be freed using EITHER delete OR IPluginIterator::Release(). 00340 */ 00341 virtual IPluginIterator *GetPluginIterator() =0; 00342 00343 /** 00344 * @brief Adds a plugin manager listener. 00345 * 00346 * @param listener Pointer to a listener. 00347 */ 00348 virtual void AddPluginsListener(IPluginsListener *listener) =0; 00349 00350 /** 00351 * @brief Removes a plugin listener. 00352 * 00353 * @param listener Pointer to a listener. 00354 */ 00355 virtual void RemovePluginsListener(IPluginsListener *listener) =0; 00356 }; 00357 } 00358 00359 #endif //_INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_
1.5.1