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