finalized new structure and imported newly proposed plugin system API

added zlib to source tree added VM API to source tree --HG-- extra : convert_revision : svn%3A39bc706e-5318-0410-9160-8a85361fbb7c/trunk%40164
2006-11-08 06:30:20 +00:00
parent 4242e06465
commit 65026ef57e
32 changed files with 12167 additions and 23 deletions
@@ -2,12 +2,50 @@
 #define _INCLUDE_SOURCEMOD_PLUGINMNGR_INTERFACE_H_

 #include <IShareSys.h>
+#include <sp_vm_context.h>

 #define SMINTERFACE_PLUGINMANAGER_NAME		"IPluginManager"
 #define SMINTERFACE_PLUGINMANAGER_VERSION	1

 namespace SourceMod
 {
+	/** 
+	 * @brief Encapsulates plugin public information.
+	 */
+	typedef struct sm_plugininfo_s
+	{
+		const char *name;
+		const char *author;
+		const char *description;
+		const char *version;
+		const char *url;
+	} sm_plugininfo_t;
+
+	/**
+	 * @brief Describes the usability status of a plugin.
+	 */
+	enum PluginStatus
+	{
+		Plugin_Running=0,		/* Plugin is running */
+		Plugin_Paused,			/* Plugin is paused */
+		Plugin_Stopped,			/* Plugin is paused for map changes, too */
+		Plugin_Error,			/* Plugin has a blocking error */
+		Plugin_BadLoad,			/* Plugin failed to load */
+	};
+
+	/**
+	 * @brief Describes the object lifetime of a plugin.
+	 */
+	enum PluginLifetime
+	{
+		PluginLifetime_Forever,			/* Plugin will never be unloaded */
+		PluginLifetime_Map				/* Plugin will be unloaded at mapchange */
+	};
+
+
+	/**
+	 * @brief Encapsulates a run-time plugin as maintained by SourceMod.
+	 */
 	class IPlugin : public IUnloadableParent
 	{
 	public:
@@ -15,14 +53,108 @@ namespace SourceMod
 		{
 			return ParentType_Module;
 		}
+	public:
+		/**
+		 * @brief Returns the lifetime of a plugin.
+		 */
+		virtual PluginLifetime GetLifetime() =0;
+
+		/**
+		 * @brief Returns the current API context being used in the plugin.
+		 *
+		 * @return	Pointer to an IPluginContext, or NULL if not loaded.
+		 */
+		virtual SourcePawn::IPluginContext *GetBaseContext() =0;
+
+		/**
+		 * @brief Returns the context structure being used in the plugin.
+		 *
+		 * @brief	Pointer to an sp_context_t, or NULL if not loaded.
+		 */
+		virtual sp_context_t *GetContext() =0;
+
+		/**
+		 * @brief Returns information about the plugin.
+		 *
+		 * @brief	Pointer to an sm_plugininfo_t, or NULL if not loaded.
+		 */
+		virtual 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 pause, false otherwise.
+		 */
+		virtual bool SetPauseState(bool paused) =0;
+
+		/**
+		 * @brief Locks or unlocks the plugin from being updated on mapchange.
+		 */
+		virtual void SetLockForUpdates(bool lock_status) =0;
+
+		/**
+		 * @brief Returns whether the plugin is locked from being updated on mapchange.
+		 */
+		virtual bool GetLockForUpdates() =0;
+
+		/**
+		 * @brief Returns the unique serial number of a plugin.
+		 */
+		virtual unsigned int GetSerial() =0;
 	};

-	enum PluginLifetime
+
+	/**
+	 * @brief Iterates over a list of plugins.
+	 */
+	class IPluginIterator
 	{
-		PluginLifetime_Forever,
-		PluginLifetime_Map
+	public:
+		virtual void ~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 Manages the runtime loading and unloading of plugins.
+	 */
 	class IPluginManager : public SMInterface
 	{
 	public:
@@ -40,7 +172,6 @@ namespace SourceMod
 		 * @brief Attempts to load a plugin.
 		 *
 		 * @param path		Path and filename of plugin, relative to plugins folder.
-		 * @param extended	Whether or not the plugin is a static plugin or optional plugin.
 		 * @param debug		Whether or not to default the plugin into debug mode.
 		 * @param lifetime	Lifetime of the plugin.
 		 * @param error		Buffer to hold any error message.
@@ -48,11 +179,40 @@ namespace SourceMod
 		 * @return			A new plugin pointer on success, false otherwise.
 		 */
 		virtual IPlugin *LoadPlugin(const char *path, 
-									bool extended, 
 									bool debug,
 									PluginLifetime lifetime,
 									char error[],
 									size_t err_max) =0;
+
+		/**
+		 * @brief Attempts to unload a plugin.
+		 *
+		 * @param			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			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;
 	};
 };

@@ -140,25 +140,40 @@ namespace SourceMod
 	public:
 		enum SMCParseResult
 		{
-			SMCParse_Continue,
-			SMCParse_SkipSection,
-			SMCParse_Halt,
-			SMCParse_HaltFail
+			SMCParse_Continue,		//continue parsing
+			SMCParse_SkipSection,	//skip the rest of the current section
+			SMCParse_Halt,			//stop parsing here
+			SMCParse_HaltFail		//stop parsing and return failure
 		};

+		/**
+		 * @brief Called when starting parsing.
+		 */
+		virtual void ReadSMC_ParseStart()
+		{
+		};
+
+		/**
+		 * @brief Called when ending parsing.
+		 *
+		 * @param halted			True if abnormally halted, false otherwise.
+		 * @param failed			True if parsing failed, false otherwise.
+		 */
+		virtual void ReadSMC_ParseEnd(bool halted, bool failed)
+		{
+		}
+
 		/**
 		 * @brief Called when entering a new section
 		 *
 		 * @param name			Name of section, with the colon omitted.
 		 * @param option		Optional text after the colon, quotes removed.  NULL if none.
 		 * @param colon			Whether or not the required ':' was encountered.
-		 * @param start_token	Whether a start token was detected.
 		 * @return				SMCParseResult directive.
 		 */
 		virtual SMCParseResult ReadSMC_NewSection(const char *name, 
 													const char *option, 
-													bool colon, 
-													bool start_token)
+													bool colon)
 		{
 			return SMCParse_Continue;
 		}
@@ -183,11 +198,23 @@ namespace SourceMod

 		/**
 		 * @brief Called when leaving the current section.
+		 * Note: Skipping the section has no meaning here.
 		 *
-		 * @param end_token		Whether an end token was detected.
 		 * @return				SMCParseResult directive.
 		 */
-		virtual SMCParseResult ReadSMC_LeavingSection(bool end_token)
+		virtual SMCParseResult ReadSMC_LeavingSection()
+		{
+			return SMCParse_Continue;
+		}
+
+		/**
+		 * @brief Called after an input line has been preprocessed.
+		 *
+		 * @param line			String containing line input.
+		 * @param curline		Number of line in file.
+		 * @return				SMCParseResult directive.
+		 */
+		virtual SMCParseResult ReadSMC_RawLine(const char *line, unsigned int curline)
 		{
 			return SMCParse_Continue;
 		}
@@ -232,12 +259,14 @@ namespace SourceMod
 		 * @param smc_listener	Event handler for reading file.
 		 * @param line			If non-NULL, will contain last line parsed (0 if file could not be opened).
 		 * @param col			If non-NULL, will contain last column parsed (undefined if file could not be opened).
+		 * @param strict		If strict mode is enabled, the parsing rules are obeyed rigorously rather than loosely.
 		 * @return				True if parsing succeded, false if file couldn't be opened or there was a syntax error.
 		 */
 		virtual bool ParseFile_SMC(const char *file, 
 									ITextListener_SMC *smc_listener, 
 									unsigned int *line, 
-									unsigned int *col) =0;
+									unsigned int *col,
+									bool strict) =0;
 	public:
 		/**
 		 * @brief Returns the number of bytes that a multi-byte character contains in a UTF-8 stream.