dvander@372: /**
dvander@375:  * vim: set ts=4 :
dvander@372:  * ===============================================================
dvander@376:  * SourceMod, Copyright (C) 2004-2007 AlliedModders LLC. 
dvander@376:  * All rights reserved.
dvander@372:  * ===============================================================
dvander@372:  *
dvander@379:  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be 
dvander@379:  * used or modified under the Terms and Conditions of its License Agreement, 
dvander@379:  * which is found in public/licenses/LICENSE.txt.  As of this notice, derivative 
dvander@379:  * works must be licensed under the GNU General Public License (version 2 or 
dvander@379:  * greater).  A copy of the GPL is included under public/licenses/GPL.txt.
dvander@379:  * 
dvander@379:  * To view the latest information, see: http://www.sourcemod.net/license.php
dvander@372:  *
dvander@372:  * Version: $Id$
dvander@372:  */
dvander@372: 
dvander@324: #ifndef _INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_
dvander@324: #define _INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_
dvander@324: 
dvander@372: /**
dvander@372:  * @file IPluginSys.h
dvander@372:  * @brief Defines the interface for the Plugin System, which manages loaded plugins.
dvander@372:  */
dvander@372: 
dvander@324: #include <IShareSys.h>
dvander@324: #include <sp_vm_api.h>
dvander@324: 
dvander@324: #define SMINTERFACE_PLUGINSYSTEM_NAME		"IPluginManager"
dvander@486: #define SMINTERFACE_PLUGINSYSTEM_VERSION	2
dvander@324: 
dvander@372: /** Context user slot 3 is used Core for holding an IPluginContext pointer. */
dvander@324: #define SM_CONTEXTVAR_USER		3
dvander@324: 
dvander@324: namespace SourceMod
dvander@324: {
dvander@324: 	class IPlugin;
dvander@324: 
dvander@324: 	/** 
dvander@372: 	 * @brief Encapsulates plugin public information exposed through "myinfo."
dvander@324: 	 */
dvander@324: 	typedef struct sm_plugininfo_s
dvander@324: 	{
dvander@372: 		const char *name;			/**< Plugin name */
dvander@372: 		const char *author;			/**< Plugin author */
dvander@372: 		const char *description;	/**< Plugin description */
dvander@372: 		const char *version;		/**< Plugin version string */
dvander@372: 		const char *url;			/**< Plugin URL */
dvander@324: 	} sm_plugininfo_t;
dvander@324: 
dvander@324: 
dvander@324: 	/**
dvander@324: 	 * @brief Describes the usability status of a plugin.
dvander@324: 	 */
dvander@324: 	enum PluginStatus
dvander@324: 	{
dvander@372: 		Plugin_Running=0,		/**< Plugin is running */
dvander@324: 		/* All states below are unexecutable */
dvander@372: 		Plugin_Paused,			/**< Plugin is loaded but paused */
dvander@372: 		Plugin_Error,			/**< Plugin is loaded but errored/locked */
dvander@324: 		/* All states below do not have all natives */
dvander@372: 		Plugin_Loaded,			/**< Plugin has passed loading and can be finalized */
dvander@372: 		Plugin_Failed,			/**< Plugin has a fatal failure */
dvander@372: 		Plugin_Created,			/**< Plugin is created but not initialized */
dvander@372: 		Plugin_Uncompiled,		/**< Plugin is not yet compiled by the JIT */
dvander@372: 		Plugin_BadLoad,			/**< Plugin failed to load */
dvander@324: 	};
dvander@324: 
dvander@324: 
dvander@324: 	/**
dvander@324: 	 * @brief Describes the object lifetime of a plugin.
dvander@324: 	 */
dvander@324: 	enum PluginType
dvander@324: 	{
dvander@372: 		PluginType_Private,			/**< Plugin is privately managed and receives no forwards */
dvander@372: 		PluginType_MapUpdated,		/**< Plugin will never be unloaded unless for updates on mapchange */
dvander@372: 		PluginType_MapOnly,			/**< Plugin will be removed at mapchange */
dvander@372: 		PluginType_Global,			/**< Plugin will never be unloaded or updated */
dvander@324: 	};
dvander@324: 
dvander@324: 	/**
dvander@324: 	 * @brief Encapsulates a run-time plugin as maintained by SourceMod.
dvander@324: 	 */
dvander@324: 	class IPlugin
dvander@324: 	{
dvander@324: 	public:
dvander@372: 		/** Virtual destructor */
dvander@324: 		virtual ~IPlugin()
dvander@324: 		{
dvander@324: 		}
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Returns the lifetime of a plugin.
dvander@324: 		 */
dvander@324: 		virtual PluginType GetType() const =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Returns the current API context being used in the plugin.
dvander@324: 		 *
dvander@324: 		 * @return	Pointer to an IPluginContext, or NULL if not loaded.
dvander@324: 		 */
dvander@324: 		virtual SourcePawn::IPluginContext *GetBaseContext() const =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Returns the context structure being used in the plugin.
dvander@324: 		 *
dvander@324: 		 * @return	Pointer to an sp_context_t, or NULL if not loaded.
dvander@324: 		 */
dvander@324: 		virtual sp_context_t *GetContext() const =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Returns the plugin file structure.
dvander@324: 		 *
dvander@324: 		 * @return	Pointer to an sp_plugin_t, or NULL if not loaded.
dvander@324: 		 */
dvander@324: 		virtual const sp_plugin_t *GetPluginStructure() const =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Returns information about the plugin by reference.
dvander@324: 		 *
dvander@324: 		 * @return			Pointer to a sm_plugininfo_t object, NULL if plugin is not loaded.
dvander@324: 		 */
dvander@324: 		virtual const sm_plugininfo_t *GetPublicInfo() const =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Returns the plugin filename (relative to plugins dir).
dvander@324: 		 */
dvander@324: 		virtual const char *GetFilename() const =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Returns true if a plugin is in debug mode, false otherwise.
dvander@324: 		 */
dvander@324: 		virtual bool IsDebugging() const =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Returns the plugin status.
dvander@324: 		 */
dvander@324: 		virtual PluginStatus GetStatus() const =0;
dvander@324: 		
dvander@324: 		/**
dvander@324: 		 * @brief Sets whether the plugin is paused or not.
dvander@324: 		 *
dvander@324: 		 * @return			True on successful state change, false otherwise.
dvander@324: 		 */
dvander@324: 		virtual bool SetPauseState(bool paused) =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Returns the unique serial number of a plugin.
dvander@324: 		 */
dvander@324: 		virtual unsigned int GetSerial() const =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Returns a plugin's identity token.
dvander@324: 		 */
dvander@324: 		virtual IdentityToken_t *GetIdentity() const =0;
dvander@486: 
dvander@486: 		/**
dvander@486: 		 * @brief Sets a property on this plugin.  This is used for per-plugin
dvander@486: 		 * data from extensions or other parts of core.  The property's value must 
dvander@486: 		 * be manually destructed when the plugin is destroyed.
dvander@486: 		 *
dvander@486: 		 * @param prop		String containing name of the property.
dvander@486: 		 * @param ptr		Generic pointer to set.
dvander@486: 		 * @return			True on success, false if the property is already set.
dvander@486: 		 */
dvander@486: 		virtual bool SetProperty(const char *prop, void *ptr) =0;
dvander@486: 
dvander@486: 		/**
dvander@486: 		 * @brief Gets a property from a plugin.
dvander@486: 		 *
dvander@486: 		 * @param prop		String containing the property's name.
dvander@486: 		 * @param ptr		Optional pointer to the generic pointer.
dvander@486: 		 * @param remove	Optional boolean value; if true, property is removed
dvander@486: 		 *					(so it can be set again).
dvander@486: 		 * @return			True if the property existed, false otherwise.
dvander@486: 		 */
dvander@486: 		virtual bool GetProperty(const char *prop, void **ptr, bool remove=false) =0;
dvander@324: 	};
dvander@324: 
dvander@324: 
dvander@324: 	/**
dvander@324: 	 * @brief Iterates over a list of plugins.
dvander@324: 	 */
dvander@324: 	class IPluginIterator
dvander@324: 	{
dvander@324: 	public:
dvander@372: 		/** Virtual destructor */
dvander@324: 		virtual ~IPluginIterator()
dvander@324: 		{
dvander@324: 		};
dvander@324: 	public:
dvander@324: 		/**
dvander@324: 		 * @brief Returns true if there are more plugins in the iterator.
dvander@324: 		 */
dvander@324: 		virtual bool MorePlugins() =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Returns the plugin at the current iterator position.
dvander@324: 		 */
dvander@324: 		virtual IPlugin *GetPlugin() =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Advances to the next plugin in the iterator.
dvander@324: 		 */
dvander@324: 		virtual void NextPlugin() =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Destroys the iterator object.
dvander@324: 		 * Note: You may use 'delete' in lieu of this function.
dvander@324: 		 */
dvander@324: 		virtual void Release() =0;
dvander@324: 	};
dvander@324: 
dvander@324: 	/**
dvander@324: 	 * @brief Listens for plugin-oriented events.
dvander@324: 	 */
dvander@324: 	class IPluginsListener
dvander@324: 	{
dvander@324: 	public:
dvander@324: 		/**
dvander@324: 		 * @brief Called when a plugin is created/mapped into memory.
dvander@324: 		 */
dvander@324: 		virtual void OnPluginCreated(IPlugin *plugin)
dvander@324: 		{
dvander@324: 		}
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Called when a plugin is fully loaded successfully.
dvander@324: 		 */
dvander@324: 		virtual void OnPluginLoaded(IPlugin *plugin)
dvander@324: 		{
dvander@324: 		}
dvander@324: 
dvander@324: 		/**
faluco@430: 		* @brief Called when a plugin is paused or unpaused.
faluco@430: 		*/
faluco@430: 		virtual void OnPluginPauseChange(IPlugin *plugin, bool paused)
faluco@430: 		{
faluco@430: 		}
faluco@430: 
faluco@430: 		/**
dvander@324: 		 * @brief Called when a plugin is unloaded (only if fully loaded).
dvander@324: 		 */
dvander@324: 		virtual void OnPluginUnloaded(IPlugin *plugin)
dvander@324: 		{
dvander@324: 		}
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Called when a plugin is destroyed.
dvander@324: 		 * NOTE: Always called if Created, even if load failed.
dvander@324: 		 */
dvander@324: 		virtual void OnPluginDestroyed(IPlugin *plugin)
dvander@324: 		{
dvander@324: 		}
dvander@324: 	};
dvander@324: 
dvander@324: 
dvander@324: 	/**
dvander@324: 	 * @brief Manages the runtime loading and unloading of plugins.
dvander@324: 	 */
dvander@324: 	class IPluginManager : public SMInterface
dvander@324: 	{
dvander@324: 	public:
dvander@324: 		virtual const char *GetInterfaceName()
dvander@324: 		{
dvander@324: 			return SMINTERFACE_PLUGINSYSTEM_NAME;
dvander@324: 		}
dvander@324: 
dvander@324: 		virtual unsigned int GetInterfaceVersion()
dvander@324: 		{
dvander@324: 			return SMINTERFACE_PLUGINSYSTEM_VERSION;
dvander@324: 		}
dvander@324: 	public:
dvander@324: 		/**
dvander@324: 		 * @brief Attempts to load a plugin.
dvander@324: 		 *
dvander@324: 		 * @param path		Path and filename of plugin, relative to plugins folder.
dvander@324: 		 * @param debug		Whether or not to default the plugin into debug mode.
dvander@324: 		 * @param type		Lifetime of the plugin.
dvander@324: 		 * @param error		Buffer to hold any error message.
dvander@324: 		 * @param err_max	Maximum length of error message buffer.
faluco@383: 		 * @param wasloaded	Stores if the plugin is already loaded.
dvander@324: 		 * @return			A new plugin pointer on success, false otherwise.
dvander@324: 		 */
dvander@324: 		virtual IPlugin *LoadPlugin(const char *path, 
dvander@324: 									bool debug,
dvander@324: 									PluginType type,
dvander@324: 									char error[],
faluco@383: 									size_t err_max,
faluco@383: 									bool *wasloaded) =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Attempts to unload a plugin.
dvander@324: 		 *
dvander@324: 		 * @param plugin	Pointer to the plugin handle.
dvander@324: 		 * @return			True on success, false otherwise.
dvander@324: 		 */
dvander@324: 		virtual bool UnloadPlugin(IPlugin *plugin) =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Finds a plugin by its context.
dvander@324: 		 * Note: This function should be considered O(1).
dvander@324: 		 *
dvander@324: 		 * @param ctx		Pointer to an sp_context_t.
dvander@324: 		 * @return			Pointer to a matching IPlugin, or NULL if none found.
dvander@324: 		 */
dvander@324: 		virtual IPlugin *FindPluginByContext(const sp_context_t *ctx) =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Returns the number of plugins (both failed and loaded).
dvander@324: 		 *
dvander@324: 		 * @return			The number of internally cached plugins.
dvander@324: 		 */
dvander@324: 		virtual unsigned int GetPluginCount() =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Returns a pointer that can be used to iterate through plugins.
dvander@324: 		 * Note: This pointer must be freed using EITHER delete OR IPluginIterator::Release().
dvander@324: 		 */
dvander@324: 		virtual IPluginIterator *GetPluginIterator() =0;
dvander@324: 
dvander@324: 		/** 
dvander@324: 		 * @brief Adds a plugin manager listener.
dvander@324: 		 *
dvander@324: 		 * @param listener	Pointer to a listener.
dvander@324: 		 */
dvander@324: 		virtual void AddPluginsListener(IPluginsListener *listener) =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Removes a plugin listener.
dvander@324: 		 * 
dvander@324: 		 * @param listener	Pointer to a listener.
dvander@324: 		 */
dvander@324: 		virtual void RemovePluginsListener(IPluginsListener *listener) =0;
dvander@324: 	};
ds@432: }
dvander@324: 
dvander@324: #endif //_INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_