/**

  * vim: set ts=4 sw=4 :

  * =============================================================================

  * SourceMod

  * Copyright (C) 2004-2009 AlliedModders LLC.  All rights reserved.

  * =============================================================================

  *

  * This program is free software; you can redistribute it and/or modify it under

  * the terms of the GNU General Public License, version 3.0, as published by the

  * Free Software Foundation.

  * 

  * This program 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 General Public License for more

  * details.

  *

  * You should have received a copy of the GNU General Public License along with

  * this program.  If not, see <http://www.gnu.org/licenses/>.

  *

  * As a special exception, AlliedModders LLC gives you permission to link the

  * code of this program (as well as its derivative works) to "Half-Life 2," the

  * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software

  * by the Valve Corporation.  You must obey the GNU General Public License in

  * all respects for all other code used.  Additionally, AlliedModders LLC grants

  * this exception to all derivative works.  AlliedModders LLC defines further

  * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),

  * or <http://www.sourcemod.net/license.php>.

  *

  * Version: $Id$

  */

 #ifndef _INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_

 #define _INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_

 /**

  * @file IPluginSys.h

  * @brief Defines the interface for the Plugin System, which manages loaded plugins.

  */

 #include <IShareSys.h>

 #include <IHandleSys.h>

 #include <sp_vm_api.h>

 #define SMINTERFACE_PLUGINSYSTEM_NAME		"IPluginManager"

 #define SMINTERFACE_PLUGINSYSTEM_VERSION	3

 /** Context user slot 3 is used Core for holding an IPluginContext pointer. */

 #define SM_CONTEXTVAR_USER		3

 namespace SourceMod

 {

 	class IPlugin;

 	/** 

 	 * @brief Encapsulates plugin public information exposed through "myinfo."

 	 */

 	typedef struct sm_plugininfo_s

 	{

 		const char *name;			/**< Plugin name */

 		const char *author;			/**< Plugin author */

 		const char *description;	/**< Plugin description */

 		const char *version;		/**< Plugin version string */

 		const char *url;			/**< Plugin URL */

 	} sm_plugininfo_t;

 	/**

 	 * @brief Describes the usability status of a plugin.

 	 */

 	enum PluginStatus

 	{

 		Plugin_Running=0,		/**< Plugin is running */

 		/* All states below are unexecutable */

 		Plugin_Paused,			/**< Plugin is loaded but paused */

 		Plugin_Error,			/**< Plugin is loaded but errored/locked */

 		/* All states below do not have all natives */

 		Plugin_Loaded,			/**< Plugin has passed loading and can be finalized */

 		Plugin_Failed,			/**< Plugin has a fatal failure */

 		Plugin_Created,			/**< Plugin is created but not initialized */

 		Plugin_Uncompiled,		/**< Plugin is not yet compiled by the JIT */

 		Plugin_BadLoad,			/**< Plugin failed to load */

 	};

 	/**

 	 * @brief Describes the object lifetime of a plugin.

 	 */

 	enum PluginType

 	{

 		PluginType_Private,			/**< Plugin is privately managed and receives no forwards */

 		PluginType_MapUpdated,		/**< Plugin will never be unloaded unless for updates on mapchange */

 		PluginType_MapOnly,			/**< Plugin will be removed at mapchange */

 		PluginType_Global,			/**< Plugin will never be unloaded or updated */

 	};

 	/**

 	 * @brief Encapsulates a run-time plugin as maintained by SourceMod.

 	 */

 	class IPlugin

 	{

 	public:

 		/** Virtual destructor */

 		virtual ~IPlugin()

 		{

 		}

 		/**

 		 * @brief Returns the lifetime of a plugin.

 		 */

 		virtual PluginType GetType() =0;

 		/**

 		 * @brief Returns the IPluginRuntime::GetDefaultContext() value.

 		 *

 		 * @return	Pointer to an IPluginContext, or NULL if not loaded.

 		 */

 		virtual SourcePawn::IPluginContext *GetBaseContext() =0;

 		/**

 		 * @brief Deprecated, returns NULL.

 		 *

 		 * @return	NULL.

 		 */

 		virtual sp_context_t *GetContext() =0;

 		/**

 		 * @brief Deprecated, returns NULL.

 		 *

 		 * @return	NULL.

 		 */

 		virtual void *GetPluginStructure() =0;

 		/**

 		 * @brief Returns information about the plugin by reference.

 		 *

 		 * @return			Pointer to a sm_plugininfo_t object, NULL if plugin is not loaded.

 		 */

 		virtual const sm_plugininfo_t *GetPublicInfo() =0;

 		/**

 		 * @brief Returns the plugin filename (relative to plugins dir).

 		 */

 		virtual const char *GetFilename() =0;

 		/**

 		 * @brief Returns true if a plugin is in debug mode, false otherwise.

 		 */

 		virtual bool IsDebugging() =0;

 		/**

 		 * @brief Returns the plugin status.

 		 */

 		virtual PluginStatus GetStatus() =0;

 		/**

 		 * @brief Sets whether the plugin is paused or not.

 		 *

 		 * @return			True on successful state change, false otherwise.

 		 */

 		virtual bool SetPauseState(bool paused) =0;

 		/**

 		 * @brief Returns the unique serial number of a plugin.

 		 */

 		virtual unsigned int GetSerial() =0;

 		/**

 		 * @brief Returns a plugin's identity token.

 		 */

 		virtual IdentityToken_t *GetIdentity() =0;

 		/**

 		 * @brief Sets a property on this plugin.  This is used for per-plugin

 		 * data from extensions or other parts of core.  The property's value must 

 		 * be manually destructed when the plugin is destroyed.

 		 *

 		 * @param prop		String containing name of the property.

 		 * @param ptr		Generic pointer to set.

 		 * @return			True on success, false if the property is already set.

 		 */

 		virtual bool SetProperty(const char *prop, void *ptr) =0;

 		/**

 		 * @brief Gets a property from a plugin.

 		 *

 		 * @param prop		String containing the property's name.

 		 * @param ptr		Optional pointer to the generic pointer.

 		 * @param remove	Optional boolean value; if true, property is removed

 		 *					(so it can be set again).

 		 * @return			True if the property existed, false otherwise.

 		 */

 		virtual bool GetProperty(const char *prop, void **ptr, bool remove=false) =0;

 		/**

 		 * @brief Returns the runtime representing this plugin.

 		 *

 		 * @return			IPluginRuntime pointer, or NULL if not loaded.

 		 */

 		virtual SourcePawn::IPluginRuntime *GetRuntime() =0;

 	};

 	/**

 	 * @brief Iterates over a list of plugins.

 	 */

 	class IPluginIterator

 	{

 	public:

 		/** Virtual destructor */

 		virtual ~IPluginIterator()

 		{

 		};

 	public:

 		/**

 		 * @brief Returns true if there are more plugins in the iterator.

 		 */

 		virtual bool MorePlugins() =0;

 		/**

 		 * @brief Returns the plugin at the current iterator position.

 		 */

 		virtual IPlugin *GetPlugin() =0;

 		/**

 		 * @brief Advances to the next plugin in the iterator.

 		 */

 		virtual void NextPlugin() =0;

 		/**

 		 * @brief Destroys the iterator object.

 		 * Note: You may use 'delete' in lieu of this function.

 		 */

 		virtual void Release() =0;

 	};

 	/**

 	 * @brief Listens for plugin-oriented events.

 	 */

 	class IPluginsListener

 	{

 	public:

 		/**

 		 * @brief Called when a plugin is created/mapped into memory.

 		 */

 		virtual void OnPluginCreated(IPlugin *plugin)

 		{

 		}

 		/**

 		 * @brief Called when a plugin is fully loaded successfully.

 		 */

 		virtual void OnPluginLoaded(IPlugin *plugin)

 		{

 		}

 		/**

 		* @brief Called when a plugin is paused or unpaused.

 		*/

 		virtual void OnPluginPauseChange(IPlugin *plugin, bool paused)

 		{

 		}

 		/**

 		 * @brief Called when a plugin is unloaded (only if fully loaded).

 		 */

 		virtual void OnPluginUnloaded(IPlugin *plugin)

 		{

 		}

 		/**

 		 * @brief Called when a plugin is destroyed.

 		 * NOTE: Always called if Created, even if load failed.

 		 */

 		virtual void OnPluginDestroyed(IPlugin *plugin)

 		{

 		}

 	};

 	/**

 	 * @brief Manages the runtime loading and unloading of plugins.

 	 */

 	class IPluginManager : public SMInterface

 	{

 	public:

 		virtual const char *GetInterfaceName()

 		{

 			return SMINTERFACE_PLUGINSYSTEM_NAME;

 		}

 		virtual unsigned int GetInterfaceVersion()

 		{

 			return SMINTERFACE_PLUGINSYSTEM_VERSION;

 		}

 	public:

 		/**

 		 * @brief Attempts to load a plugin.

 		 *

 		 * @param path		Path and filename of plugin, relative to plugins folder.

 		 * @param debug		Deprecated, must be false.

 		 * @param type		Lifetime of the plugin.

 		 * @param error		Buffer to hold any error message.

 		 * @param maxlength	Maximum length of error message buffer.

 		 * @param wasloaded	Stores if the plugin is already loaded.

 		 * @return			A new plugin pointer on success, false otherwise.

 		 */

 		virtual IPlugin *LoadPlugin(const char *path, 

 									bool debug,

 									PluginType type,

 									char error[],

 									size_t maxlength,

 									bool *wasloaded) =0;

 		/**

 		 * @brief Attempts to unload a plugin.

 		 *

 		 * @param plugin	Pointer to the plugin handle.

 		 * @return			True on success, false otherwise.

 		 */

 		virtual bool UnloadPlugin(IPlugin *plugin) =0;

 		/**

 		 * @brief Finds a plugin by its context.

 		 * Note: This function should be considered O(1).

 		 *

 		 * @param ctx		Pointer to an sp_context_t.

 		 * @return			Pointer to a matching IPlugin, or NULL if none found.

 		 */

 		virtual IPlugin *FindPluginByContext(const sp_context_t *ctx) =0;

 		/**

 		 * @brief Returns the number of plugins (both failed and loaded).

 		 *

 		 * @return			The number of internally cached plugins.

 		 */

 		virtual unsigned int GetPluginCount() =0;

 		/**

 		 * @brief Returns a pointer that can be used to iterate through plugins.

 		 * Note: This pointer must be freed using EITHER delete OR IPluginIterator::Release().

 		 */

 		virtual IPluginIterator *GetPluginIterator() =0;

 		/** 

 		 * @brief Adds a plugin manager listener.

 		 *

 		 * @param listener	Pointer to a listener.

 		 */

 		virtual void AddPluginsListener(IPluginsListener *listener) =0;

 		/**

 		 * @brief Removes a plugin listener.

 		 * 

 		 * @param listener	Pointer to a listener.

 		 */

 		virtual void RemovePluginsListener(IPluginsListener *listener) =0;

 		/**

 		 * @brief Converts a Handle to an IPlugin if possible.

 		 *

 		 * @param handle	Handle.

 		 * @param err		Error, set on failure (otherwise undefined).

 		 * @return			IPlugin pointer, or NULL on failure.

 		 */

 		virtual IPlugin *PluginFromHandle(Handle_t handle, HandleError *err) =0;

 	};

 }

 #endif //_INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_