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_MODULE_INTERFACE_H_ dvander@324: #define _INCLUDE_SOURCEMOD_MODULE_INTERFACE_H_ dvander@324: dvander@324: #include dvander@324: #include dvander@324: dvander@372: /** dvander@372: * @file IExtensionSys.h dvander@372: * @brief Defines the interface for loading/unloading/managing extensions. dvander@372: */ dvander@372: dvander@324: namespace SourceMod dvander@324: { dvander@324: class IExtensionInterface; dvander@372: typedef void * ITERATOR; /**< Generic pointer for dependency iterators */ dvander@324: dvander@324: /** dvander@372: * @brief Encapsulates an IExtensionInterface and its dependencies. dvander@324: */ dvander@324: class IExtension dvander@324: { dvander@324: public: dvander@324: /** dvander@324: * @brief Returns whether or not the extension is properly loaded. dvander@324: */ dvander@324: virtual bool IsLoaded() =0; dvander@324: dvander@324: /** dvander@324: * @brief Returns the extension's API interface dvander@324: * dvander@324: * @return An IExtensionInterface pointer. dvander@324: */ dvander@324: virtual IExtensionInterface *GetAPI() =0; dvander@324: dvander@324: /** dvander@324: * @brief Returns the filename of the extension, relative to the dvander@324: * extension folder. dvander@324: * dvander@324: * @return A string containing the extension file name. dvander@324: */ dvander@324: virtual const char *GetFilename() =0; dvander@324: dvander@324: /** dvander@324: * @brief Returns the extension's identity token. dvander@324: * dvander@324: * @return An IdentityToken_t pointer. dvander@324: */ dvander@324: virtual IdentityToken_t *GetIdentity() =0; dvander@324: dvander@324: /** dvander@324: * @brief Retrieves the extension dependency list for this extension. dvander@324: * dvander@324: * @param pOwner Optional pointer to store the first interface's owner. dvander@324: * @param pInterface Optional pointer to store the first interface. dvander@324: * @return An ITERATOR pointer for the results, or NULL if no results at all. dvander@324: */ dvander@324: virtual ITERATOR *FindFirstDependency(IExtension **pOwner, SMInterface **pInterface) =0; dvander@324: dvander@324: /** dvander@324: * @brief Finds the next dependency in the dependency list. dvander@324: * dvander@324: * @param iter Pointer to iterator from FindFirstDependency. dvander@324: * @param pOwner Optional pointer to store the interface's owner. dvander@324: * @param pInterface Optional pointer to store the interface. dvander@324: * @return True if there are more results after this, false otherwise. dvander@324: */ dvander@324: virtual bool FindNextDependency(ITERATOR *iter, IExtension **pOwner, SMInterface **pInterface) =0; dvander@324: dvander@324: /** dvander@324: * @brief Frees an ITERATOR handle from FindFirstDependency. dvander@324: * dvander@324: * @param iter Pointer to iterator to free. dvander@324: */ dvander@324: virtual void FreeDependencyIterator(ITERATOR *iter) =0; dvander@324: dvander@324: /** dvander@324: * @brief Queries the extension to see its run state. dvander@324: * dvander@324: * @param error Error buffer (may be NULL). dvander@324: * @param maxlength Maximum length of buffer. dvander@324: * @return True if extension is okay, false if not okay. dvander@324: */ dvander@324: virtual bool IsRunning(char *error, size_t maxlength) =0; dvander@324: }; dvander@324: dvander@372: /** dvander@372: * @brief Version code of the IExtensionInterface API itself. dvander@372: */ dvander@324: #define SMINTERFACE_EXTENSIONAPI_VERSION 1 dvander@324: dvander@324: /** dvander@324: * @brief The interface an extension must expose. dvander@324: */ dvander@324: class IExtensionInterface dvander@324: { dvander@324: public: dvander@372: /** Returns the interface API version */ dvander@324: virtual unsigned int GetExtensionVersion() dvander@324: { dvander@324: return SMINTERFACE_EXTENSIONAPI_VERSION; dvander@324: } dvander@324: public: dvander@324: /** dvander@324: * @brief Called when the extension is loaded. dvander@324: * dvander@324: * @param me Pointer back to extension. dvander@324: * @param sys Pointer to interface sharing system of SourceMod. dvander@324: * @param error Error buffer to print back to, if any. ds@755: * @param maxlength Maximum size of error buffer. dvander@324: * @param late If this extension was loaded "late" (i.e. manually). dvander@324: * @return True if load should continue, false otherwise. dvander@324: */ dvander@324: virtual bool OnExtensionLoad(IExtension *me, dvander@324: IShareSys *sys, dvander@324: char *error, ds@755: size_t maxlength, dvander@324: bool late) =0; dvander@324: dvander@324: /** dvander@324: * @brief Called when the extension is about to be unloaded. dvander@324: */ dvander@324: virtual void OnExtensionUnload() =0; dvander@324: dvander@324: /** dvander@324: * @brief Called when all extensions are loaded (loading cycle is done). dvander@324: * If loaded late, this will be called right after OnExtensionLoad(). dvander@324: */ dvander@324: virtual void OnExtensionsAllLoaded() =0; dvander@324: dvander@324: /** dvander@324: * @brief Called when your pause state is about to change. dvander@324: * dvander@324: * @param pause True if pausing, false if unpausing. dvander@324: */ dvander@324: virtual void OnExtensionPauseChange(bool pause) =0; dvander@324: dvander@324: /** dvander@324: * @brief Asks the extension whether it's safe to remove an external interface it's using. dvander@324: * If it's not safe, return false, and the extension will be unloaded afterwards. dvander@324: * NOTE: It is important to also hook NotifyInterfaceDrop() in order to clean up resources. dvander@324: * dvander@324: * @param pInterface Pointer to interface being dropped. dvander@324: * @return True to continue, false to unload this extension afterwards. dvander@324: */ dvander@324: virtual bool QueryInterfaceDrop(SMInterface *pInterface) dvander@324: { dvander@329: return false; dvander@324: } dvander@324: dvander@324: /** dvander@324: * @brief Notifies the extension that an external interface it uses is being removed. dvander@324: * dvander@324: * @param pInterface Pointer to interface being dropped. dvander@324: */ dvander@324: virtual void NotifyInterfaceDrop(SMInterface *pInterface) dvander@324: { dvander@324: } dvander@324: dvander@324: /** ds@755: * @brief Return false to tell Core that your extension should be considered unusable. dvander@324: * dvander@324: * @param error Error buffer. dvander@324: * @param maxlength Size of error buffer. dvander@324: * @return True on success, false otherwise. dvander@324: */ dvander@324: virtual bool QueryRunning(char *error, size_t maxlength) dvander@324: { dvander@324: return true; dvander@324: } dvander@324: public: dvander@324: virtual bool IsMetamodExtension() =0; dvander@324: virtual const char *GetExtensionName() =0; dvander@324: virtual const char *GetExtensionURL() =0; dvander@324: virtual const char *GetExtensionTag() =0; dvander@324: virtual const char *GetExtensionAuthor() =0; dvander@324: virtual const char *GetExtensionVerString() =0; dvander@324: virtual const char *GetExtensionDescription() =0; dvander@324: virtual const char *GetExtensionDateString() =0; dvander@324: }; dvander@324: dvander@324: #define SMINTERFACE_EXTENSIONMANAGER_NAME "IExtensionManager" dvander@324: #define SMINTERFACE_EXTENSIONMANAGER_VERSION 1 dvander@324: dvander@372: /** dvander@372: * @brief Not currently used. dvander@372: */ dvander@324: enum ExtensionLifetime dvander@324: { dvander@324: ExtLifetime_Forever, //Extension will never be unloaded automatically dvander@324: ExtLifetime_Map, //Extension will be unloaded at the end of the map dvander@324: }; dvander@324: dvander@372: /** dvander@372: * @brief Manages the loading/unloading of extensions. dvander@372: */ dvander@324: class IExtensionManager : public SMInterface dvander@324: { dvander@324: public: dvander@324: virtual const char *GetInterfaceName() dvander@324: { dvander@324: return SMINTERFACE_EXTENSIONMANAGER_NAME; dvander@324: } dvander@324: virtual unsigned int GetInterfaceVersion() dvander@324: { dvander@324: return SMINTERFACE_EXTENSIONMANAGER_VERSION; dvander@324: } dvander@324: public: dvander@324: /** dvander@324: * @brief Loads a extension into the extension system. dvander@324: * dvander@324: * @param path Path to extension file, relative to the extensions folder. dvander@335: * @param lifetime Lifetime of the extension (currently ignored). dvander@324: * @param error Error buffer. ds@755: * @param maxlength Maximum error buffer length. dvander@324: * @return New IExtension on success, NULL on failure. dvander@324: */ dvander@324: virtual IExtension *LoadExtension(const char *path, dvander@324: ExtensionLifetime lifetime, dvander@324: char *error, ds@755: size_t maxlength) =0; dvander@324: dvander@324: /** dvander@324: * @brief Attempts to unload a module. dvander@324: * dvander@324: * @param pExt IExtension pointer. dvander@324: * @return True if successful, false otherwise. dvander@324: */ dvander@324: virtual bool UnloadExtension(IExtension *pExt) =0; dvander@324: }; ds@432: } dvander@324: dvander@324: #endif //_INCLUDE_SOURCEMOD_MODULE_INTERFACE_H_