1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/public/IPluginSys.h Fri Jan 19 05:33:04 2007 +0000
1.3 @@ -0,0 +1,302 @@
1.4 +#ifndef _INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_
1.5 +#define _INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_
1.6 +
1.7 +#include <IShareSys.h>
1.8 +#include <sp_vm_api.h>
1.9 +
1.10 +#define SMINTERFACE_PLUGINSYSTEM_NAME "IPluginManager"
1.11 +#define SMINTERFACE_PLUGINSYSTEM_VERSION 1
1.12 +
1.13 +#define SM_CONTEXTVAR_USER 3
1.14 +
1.15 +namespace SourceMod
1.16 +{
1.17 + class IPlugin;
1.18 +
1.19 + /**
1.20 + * @brief Encapsulates plugin public information.
1.21 + */
1.22 + typedef struct sm_plugininfo_s
1.23 + {
1.24 + const char *name;
1.25 + const char *author;
1.26 + const char *description;
1.27 + const char *version;
1.28 + const char *url;
1.29 + } sm_plugininfo_t;
1.30 +
1.31 +
1.32 + /**
1.33 + * @brief Describes the usability status of a plugin.
1.34 + * Note: The status "Loaded" and "Created" are only reachable
1.35 + * during map load.
1.36 + */
1.37 + enum PluginStatus
1.38 + {
1.39 + Plugin_Running=0, /* Plugin is running */
1.40 + /* All states below are unexecutable */
1.41 + Plugin_Paused, /* Plugin is loaded but paused */
1.42 + Plugin_Error, /* Plugin is loaded but errored/locked */
1.43 + /* All states below do not have all natives */
1.44 + Plugin_Loaded, /* Plugin has passed loading and can be finalized */
1.45 + Plugin_Failed, /* Plugin has a fatal failure */
1.46 + Plugin_Created, /* Plugin is created but not initialized */
1.47 + Plugin_Uncompiled, /* Plugin is not yet compiled by the JIT */
1.48 + Plugin_BadLoad, /* Plugin failed to load */
1.49 + };
1.50 +
1.51 +
1.52 + /**
1.53 + * @brief Describes the object lifetime of a plugin.
1.54 + */
1.55 + enum PluginType
1.56 + {
1.57 + PluginType_Private, /* Plugin is privately managed and receives no forwards */
1.58 + PluginType_MapUpdated, /* Plugin will never be unloaded unless for updates on mapchange */
1.59 + PluginType_MapOnly, /* Plugin will be removed at mapchange */
1.60 + PluginType_Global, /* Plugin will never be unloaded or updated */
1.61 + };
1.62 +
1.63 + class IPluginFunction;
1.64 +
1.65 + /**
1.66 + * @brief Encapsulates a run-time plugin as maintained by SourceMod.
1.67 + */
1.68 + class IPlugin
1.69 + {
1.70 + public:
1.71 + virtual ~IPlugin()
1.72 + {
1.73 + }
1.74 +
1.75 + /**
1.76 + * @brief Returns the lifetime of a plugin.
1.77 + */
1.78 + virtual PluginType GetType() const =0;
1.79 +
1.80 + /**
1.81 + * @brief Returns the current API context being used in the plugin.
1.82 + *
1.83 + * @return Pointer to an IPluginContext, or NULL if not loaded.
1.84 + */
1.85 + virtual SourcePawn::IPluginContext *GetBaseContext() const =0;
1.86 +
1.87 + /**
1.88 + * @brief Returns the context structure being used in the plugin.
1.89 + *
1.90 + * @return Pointer to an sp_context_t, or NULL if not loaded.
1.91 + */
1.92 + virtual sp_context_t *GetContext() const =0;
1.93 +
1.94 + /**
1.95 + * @brief Returns the plugin file structure.
1.96 + *
1.97 + * @return Pointer to an sp_plugin_t, or NULL if not loaded.
1.98 + */
1.99 + virtual const sp_plugin_t *GetPluginStructure() const =0;
1.100 +
1.101 + /**
1.102 + * @brief Returns information about the plugin by reference.
1.103 + *
1.104 + * @return Pointer to a sm_plugininfo_t object, NULL if plugin is not loaded.
1.105 + */
1.106 + virtual const sm_plugininfo_t *GetPublicInfo() const =0;
1.107 +
1.108 + /**
1.109 + * @brief Returns the plugin filename (relative to plugins dir).
1.110 + */
1.111 + virtual const char *GetFilename() const =0;
1.112 +
1.113 + /**
1.114 + * @brief Returns true if a plugin is in debug mode, false otherwise.
1.115 + */
1.116 + virtual bool IsDebugging() const =0;
1.117 +
1.118 + /**
1.119 + * @brief Returns the plugin status.
1.120 + */
1.121 + virtual PluginStatus GetStatus() const =0;
1.122 +
1.123 + /**
1.124 + * @brief Sets whether the plugin is paused or not.
1.125 + *
1.126 + * @return True on successful state change, false otherwise.
1.127 + */
1.128 + virtual bool SetPauseState(bool paused) =0;
1.129 +
1.130 + /**
1.131 + * @brief Returns the unique serial number of a plugin.
1.132 + */
1.133 + virtual unsigned int GetSerial() const =0;
1.134 +
1.135 + /**
1.136 + * @brief Returns a function by name.
1.137 + *
1.138 + * @param public_name Name of the function.
1.139 + * @return A new IPluginFunction pointer, NULL if not found.
1.140 + */
1.141 + virtual IPluginFunction *GetFunctionByName(const char *public_name) =0;
1.142 +
1.143 + /**
1.144 + * @brief Returns a function by its id.
1.145 + *
1.146 + * @param func_id Function ID.
1.147 + * @return A new IPluginFunction pointer, NULL if not found.
1.148 + */
1.149 + virtual IPluginFunction *GetFunctionById(funcid_t func_id) =0;
1.150 +
1.151 + /**
1.152 + * @brief Returns a plugin's identity token.
1.153 + */
1.154 + virtual IdentityToken_t *GetIdentity() const =0;
1.155 + };
1.156 +
1.157 +
1.158 + /**
1.159 + * @brief Iterates over a list of plugins.
1.160 + */
1.161 + class IPluginIterator
1.162 + {
1.163 + public:
1.164 + virtual ~IPluginIterator()
1.165 + {
1.166 + };
1.167 + public:
1.168 + /**
1.169 + * @brief Returns true if there are more plugins in the iterator.
1.170 + */
1.171 + virtual bool MorePlugins() =0;
1.172 +
1.173 + /**
1.174 + * @brief Returns the plugin at the current iterator position.
1.175 + */
1.176 + virtual IPlugin *GetPlugin() =0;
1.177 +
1.178 + /**
1.179 + * @brief Advances to the next plugin in the iterator.
1.180 + */
1.181 + virtual void NextPlugin() =0;
1.182 +
1.183 + /**
1.184 + * @brief Destroys the iterator object.
1.185 + * Note: You may use 'delete' in lieu of this function.
1.186 + */
1.187 + virtual void Release() =0;
1.188 + };
1.189 +
1.190 + /**
1.191 + * @brief Listens for plugin-oriented events.
1.192 + */
1.193 + class IPluginsListener
1.194 + {
1.195 + public:
1.196 + /**
1.197 + * @brief Called when a plugin is created/mapped into memory.
1.198 + */
1.199 + virtual void OnPluginCreated(IPlugin *plugin)
1.200 + {
1.201 + }
1.202 +
1.203 + /**
1.204 + * @brief Called when a plugin is fully loaded successfully.
1.205 + */
1.206 + virtual void OnPluginLoaded(IPlugin *plugin)
1.207 + {
1.208 + }
1.209 +
1.210 + /**
1.211 + * @brief Called when a plugin is unloaded (only if fully loaded).
1.212 + */
1.213 + virtual void OnPluginUnloaded(IPlugin *plugin)
1.214 + {
1.215 + }
1.216 +
1.217 + /**
1.218 + * @brief Called when a plugin is destroyed.
1.219 + * NOTE: Always called if Created, even if load failed.
1.220 + */
1.221 + virtual void OnPluginDestroyed(IPlugin *plugin)
1.222 + {
1.223 + }
1.224 + };
1.225 +
1.226 +
1.227 + /**
1.228 + * @brief Manages the runtime loading and unloading of plugins.
1.229 + */
1.230 + class IPluginManager : public SMInterface
1.231 + {
1.232 + public:
1.233 + virtual const char *GetInterfaceName()
1.234 + {
1.235 + return SMINTERFACE_PLUGINSYSTEM_NAME;
1.236 + }
1.237 +
1.238 + virtual unsigned int GetInterfaceVersion()
1.239 + {
1.240 + return SMINTERFACE_PLUGINSYSTEM_VERSION;
1.241 + }
1.242 + public:
1.243 + /**
1.244 + * @brief Attempts to load a plugin.
1.245 + *
1.246 + * @param path Path and filename of plugin, relative to plugins folder.
1.247 + * @param debug Whether or not to default the plugin into debug mode.
1.248 + * @param type Lifetime of the plugin.
1.249 + * @param error Buffer to hold any error message.
1.250 + * @param err_max Maximum length of error message buffer.
1.251 + * @return A new plugin pointer on success, false otherwise.
1.252 + */
1.253 + virtual IPlugin *LoadPlugin(const char *path,
1.254 + bool debug,
1.255 + PluginType type,
1.256 + char error[],
1.257 + size_t err_max) =0;
1.258 +
1.259 + /**
1.260 + * @brief Attempts to unload a plugin.
1.261 + *
1.262 + * @param plugin Pointer to the plugin handle.
1.263 + * @return True on success, false otherwise.
1.264 + */
1.265 + virtual bool UnloadPlugin(IPlugin *plugin) =0;
1.266 +
1.267 + /**
1.268 + * @brief Finds a plugin by its context.
1.269 + * Note: This function should be considered O(1).
1.270 + *
1.271 + * @param ctx Pointer to an sp_context_t.
1.272 + * @return Pointer to a matching IPlugin, or NULL if none found.
1.273 + */
1.274 + virtual IPlugin *FindPluginByContext(const sp_context_t *ctx) =0;
1.275 +
1.276 + /**
1.277 + * @brief Returns the number of plugins (both failed and loaded).
1.278 + *
1.279 + * @return The number of internally cached plugins.
1.280 + */
1.281 + virtual unsigned int GetPluginCount() =0;
1.282 +
1.283 + /**
1.284 + * @brief Returns a pointer that can be used to iterate through plugins.
1.285 + * Note: This pointer must be freed using EITHER delete OR IPluginIterator::Release().
1.286 + */
1.287 + virtual IPluginIterator *GetPluginIterator() =0;
1.288 +
1.289 + /**
1.290 + * @brief Adds a plugin manager listener.
1.291 + *
1.292 + * @param listener Pointer to a listener.
1.293 + */
1.294 + virtual void AddPluginsListener(IPluginsListener *listener) =0;
1.295 +
1.296 + /**
1.297 + * @brief Removes a plugin listener.
1.298 + *
1.299 + * @param listener Pointer to a listener.
1.300 + */
1.301 + virtual void RemovePluginsListener(IPluginsListener *listener) =0;
1.302 + };
1.303 +};
1.304 +
1.305 +#endif //_INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_
