Home - sourcemod-central - file revision - public/IExtensionSys.h@40cc5e9f0f1b Mercurial
summary | shortlog | changelog | graph | tags | branches | files | changeset | file | latest | revisions | annotate | diff | raw | help
public/IExtensionSys.h
author Scott Ehlert <ds@alliedmods.net>
Sun Jul 15 08:00:26 2007 +0000 (2007-07-15)
changeset 1116 40cc5e9f0f1b
parent 755 66c9fde7f632
child 1226 478550a4d5ec
permissions -rw-r--r--
Removed strange debugging code 
     1 /**
     2  * vim: set ts=4 :
     3  * ===============================================================
     4  * SourceMod, Copyright (C) 2004-2007 AlliedModders LLC. 
     5  * All rights reserved.
     6  * ===============================================================
     7  *
     8  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be 
     9  * used or modified under the Terms and Conditions of its License Agreement, 
    10  * which is found in public/licenses/LICENSE.txt.  As of this notice, derivative 
    11  * works must be licensed under the GNU General Public License (version 2 or 
    12  * greater).  A copy of the GPL is included under public/licenses/GPL.txt.
    13  * 
    14  * To view the latest information, see: http://www.sourcemod.net/license.php
    15  *
    16  * Version: $Id$
    17  */
    18 
    19 #ifndef _INCLUDE_SOURCEMOD_MODULE_INTERFACE_H_
    20 #define _INCLUDE_SOURCEMOD_MODULE_INTERFACE_H_
    21 
    22 #include <IShareSys.h>
    23 #include <ILibrarySys.h>
    24 
    25 /**
    26  * @file IExtensionSys.h
    27  * @brief Defines the interface for loading/unloading/managing extensions.
    28  */
    29 
    30 namespace SourceMod
    31 {
    32 	class IExtensionInterface;
    33 	typedef void *		ITERATOR;		/**< Generic pointer for dependency iterators */
    34 
    35 	/** 
    36 	 * @brief Encapsulates an IExtensionInterface and its dependencies.
    37 	 */
    38 	class IExtension
    39 	{
    40 	public:
    41 		/**
    42 		 * @brief Returns whether or not the extension is properly loaded.
    43 		 */
    44 		virtual bool IsLoaded() =0;
    45 
    46 		/**
    47 		 * @brief Returns the extension's API interface
    48 		 *
    49 		 * @return			An IExtensionInterface pointer.
    50 		 */
    51 		virtual IExtensionInterface *GetAPI() =0;
    52 
    53 		/**
    54 		 * @brief Returns the filename of the extension, relative to the
    55 		 * extension folder.
    56 		 *
    57 		 * @return			A string containing the extension file name.
    58 		 */
    59 		virtual const char *GetFilename() =0;
    60 
    61 		/**
    62 		 * @brief Returns the extension's identity token.
    63 		 *
    64 		 * @return			An IdentityToken_t pointer.
    65 		 */
    66 		virtual IdentityToken_t *GetIdentity() =0;
    67 
    68 		/**
    69 		 * @brief Retrieves the extension dependency list for this extension.
    70 		 *
    71 		 * @param pOwner		Optional pointer to store the first interface's owner.
    72 		 * @param pInterface	Optional pointer to store the first interface.
    73 		 * @return				An ITERATOR pointer for the results, or NULL if no results at all.
    74 		 */
    75 		virtual ITERATOR *FindFirstDependency(IExtension **pOwner, SMInterface **pInterface) =0;
    76 
    77 		/**
    78 		 * @brief Finds the next dependency in the dependency list.
    79 		 *
    80 		 * @param iter			Pointer to iterator from FindFirstDependency.
    81 		 * @param pOwner		Optional pointer to store the interface's owner.
    82 		 * @param pInterface	Optional pointer to store the interface.
    83 		 * @return				True if there are more results after this, false otherwise.
    84 		 */
    85 		virtual bool FindNextDependency(ITERATOR *iter, IExtension **pOwner, SMInterface **pInterface) =0;
    86 
    87 		/**
    88 		 * @brief Frees an ITERATOR handle from FindFirstDependency.
    89 		 *
    90 		 * @param iter			Pointer to iterator to free.
    91 		 */
    92 		virtual void FreeDependencyIterator(ITERATOR *iter) =0;
    93 
    94 		/**
    95 		 * @brief Queries the extension to see its run state.
    96 		 *
    97 		 * @param error			Error buffer (may be NULL).
    98 		 * @param maxlength		Maximum length of buffer.
    99 		 * @return				True if extension is okay, false if not okay.
   100 		 */
   101 		virtual bool IsRunning(char *error, size_t maxlength) =0;
   102 	};
   103 
   104 	/**
   105 	 * @brief Version code of the IExtensionInterface API itself.
   106 	 */
   107 	#define SMINTERFACE_EXTENSIONAPI_VERSION	1
   108 
   109 	/**
   110 	 * @brief The interface an extension must expose.
   111 	 */
   112 	class IExtensionInterface
   113 	{
   114 	public:
   115 		/** Returns the interface API version */
   116 		virtual unsigned int GetExtensionVersion()
   117 		{
   118 			return SMINTERFACE_EXTENSIONAPI_VERSION;
   119 		}
   120 	public:
   121 		/**
   122 		 * @brief Called when the extension is loaded.
   123 		 * 
   124 		 * @param me		Pointer back to extension.
   125 		 * @param sys		Pointer to interface sharing system of SourceMod.
   126 		 * @param error		Error buffer to print back to, if any.
   127 		 * @param maxlength	Maximum size of error buffer.
   128 		 * @param late		If this extension was loaded "late" (i.e. manually).
   129 		 * @return			True if load should continue, false otherwise.
   130 		 */
   131 		virtual bool OnExtensionLoad(IExtension *me,
   132 								  IShareSys *sys, 
   133 								  char *error, 
   134 								  size_t maxlength, 
   135 								  bool late) =0;
   136 
   137 		/**
   138 		 * @brief Called when the extension is about to be unloaded.
   139 		 */
   140 		virtual void OnExtensionUnload() =0;
   141 
   142 		/**
   143 		 * @brief Called when all extensions are loaded (loading cycle is done).
   144 		 * If loaded late, this will be called right after OnExtensionLoad().
   145 		 */
   146 		virtual void OnExtensionsAllLoaded() =0;
   147 
   148 		/**
   149 		 * @brief Called when your pause state is about to change.
   150 		 * 
   151 		 * @param pause		True if pausing, false if unpausing.
   152 		 */
   153 		virtual void OnExtensionPauseChange(bool pause) =0;
   154 
   155 		/**
   156 		 * @brief Asks the extension whether it's safe to remove an external interface it's using.
   157 		 * If it's not safe, return false, and the extension will be unloaded afterwards.
   158 		 * NOTE: It is important to also hook NotifyInterfaceDrop() in order to clean up resources.
   159 		 *
   160 		 * @param pInterface		Pointer to interface being dropped.
   161 		 * @return					True to continue, false to unload this extension afterwards.
   162 		 */
   163 		virtual bool QueryInterfaceDrop(SMInterface *pInterface)
   164 		{
   165 			return false;
   166 		}
   167 
   168 		/**
   169 		 * @brief Notifies the extension that an external interface it uses is being removed.
   170 		 *
   171 		 * @param pInterface		Pointer to interface being dropped.
   172 		 */
   173 		virtual void NotifyInterfaceDrop(SMInterface *pInterface)
   174 		{
   175 		}
   176 
   177 		/**
   178 		 * @brief Return false to tell Core that your extension should be considered unusable.
   179 		 *
   180 		 * @param error				Error buffer.
   181 		 * @param maxlength			Size of error buffer.
   182 		 * @return					True on success, false otherwise.
   183 		 */
   184 		virtual bool QueryRunning(char *error, size_t maxlength)
   185 		{
   186 			return true;
   187 		}
   188 	public:
   189 		virtual bool IsMetamodExtension() =0;
   190 		virtual const char *GetExtensionName() =0;
   191 		virtual const char *GetExtensionURL() =0;
   192 		virtual const char *GetExtensionTag() =0;
   193 		virtual const char *GetExtensionAuthor() =0;
   194 		virtual const char *GetExtensionVerString() =0;
   195 		virtual const char *GetExtensionDescription() =0;
   196 		virtual const char *GetExtensionDateString() =0;
   197 	};
   198 
   199 	#define SMINTERFACE_EXTENSIONMANAGER_NAME			"IExtensionManager"
   200 	#define SMINTERFACE_EXTENSIONMANAGER_VERSION		1
   201 
   202 	/**
   203 	 * @brief Not currently used.
   204 	 */
   205 	enum ExtensionLifetime
   206 	{
   207 		ExtLifetime_Forever,			//Extension will never be unloaded automatically
   208 		ExtLifetime_Map,				//Extension will be unloaded at the end of the map
   209 	};
   210 
   211 	/**
   212 	 * @brief Manages the loading/unloading of extensions.
   213 	 */
   214 	class IExtensionManager : public SMInterface
   215 	{
   216 	public:
   217 		virtual const char *GetInterfaceName()
   218 		{
   219 			return SMINTERFACE_EXTENSIONMANAGER_NAME;
   220 		}
   221 		virtual unsigned int GetInterfaceVersion()
   222 		{
   223 			return SMINTERFACE_EXTENSIONMANAGER_VERSION;
   224 		}
   225 	public:
   226 		/**
   227 		 * @brief Loads a extension into the extension system.
   228 		 *
   229 		 * @param path		Path to extension file, relative to the extensions folder.
   230 		 * @param lifetime	Lifetime of the extension (currently ignored).
   231 		 * @param error		Error buffer.
   232 		 * @param maxlength	Maximum error buffer length.
   233 		 * @return			New IExtension on success, NULL on failure.
   234 		 */
   235 		virtual IExtension *LoadExtension(const char *path, 
   236 									ExtensionLifetime lifetime, 
   237 									char *error,
   238 									size_t maxlength) =0;
   239 
   240 		/**
   241 		 * @brief Attempts to unload a module.
   242 		 *
   243 		 * @param pExt		IExtension pointer.
   244 		 * @return			True if successful, false otherwise.
   245 		 */
   246 		virtual bool UnloadExtension(IExtension *pExt) =0;
   247 	};
   248 }
   249 
   250 #endif //_INCLUDE_SOURCEMOD_MODULE_INTERFACE_H_
sourcemod-central
Feed