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