sourcemm/ISmmPlugin.h
author Scott Ehlert <ds@alliedmods.net>
Mon Apr 17 19:42:55 2006 +0000 (2006-04-17)
changeset 187 d81c2fc9a708
parent 175 b497b7777f6b
child 227 b93cfe2e3a0b
permissions -rw-r--r--
Fixed a warning in stub and sample :|
     1 /* ======== SourceMM ========
     2 * Copyright (C) 2004-2006 Metamod:Source Development Team
     3 * No warranties of any kind
     4 *
     5 * License: zlib/libpng
     6 *
     7 * Author(s): David "BAILOPAN" Anderson
     8 * ============================
     9 */
    10 
    11 #ifndef _INCLUDE_ISMM_PLUGIN_H
    12 #define _INCLUDE_ISMM_PLUGIN_H
    13 
    14 /**
    15  * @brief Plugin API interface
    16  * @file ISmmPlugin.h
    17  */
    18 
    19 #include <interface.h>
    20 #include <sourcehook/sourcehook.h>
    21 #include "ISmmAPI.h"
    22 
    23 #define PLAPI_VERSION	8
    24 #define PLAPI_NAME		"ISmmPlugin"
    25 
    26 class ISmmAPI;
    27 
    28 class ISmmPlugin
    29 {
    30 public:
    31 	virtual int GetApiVersion() { return PLAPI_VERSION; }
    32 	virtual ~ISmmPlugin() { }
    33 public:
    34 	/**
    35 	 * @brief Called on plugin load.
    36 	 * NOTE - As of API 7, this is called as DLLInit() executes - after the parameters are known, but before 
    37 	 *  the original GameDLL function is called.  Therefore, you cannot hook it, but you don't need to - 
    38 	 *  Load() is basically your hook.
    39 	 * NOTE - As of API 7, you can override factories before the engine and gamedll exchange them.
    40 	 *  However, take care to note that if your plugin is unloaded, and the gamedll/engine have cached
    41 	 *  an interface you've passed, something will definitely crash.  Be careful.
    42 	 *
    43 	 * @param id	Internal id of plugin.  Saved globally by PLUGIN_SAVEVARS()
    44 	 * @param ismm	External API for SourceMM.  Saved globally by PLUGIN_SAVEVARS()
    45 	 * @param list	Contains a list of factories.  Hook a factory call by setting one equal to your own function.
    46 	 * @param late	Set to true if your plugin was loaded late (not at server load).
    47 	 * @param error Error message buffer
    48 	 * @param maxlen Size of error message buffer
    49 	 * @return		True if successful, return false to reject the load.
    50 	 */
    51 	virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0;
    52 
    53 	/**
    54 	 * @brief Called when your plugin is "queried".  This is useful for rejecting a loaded
    55 	 *  state.  For example, if your plugin wants to stop operating, it can simply return
    56 	 *  false and copy an error message.  This will notify other plugins or MM:S of something
    57 	 *  bad that happened.  NOTE - MM:S will not cache the return state, so if you return false,
    58 	 *  your plugin will not actually be paused or unloaded.  This callback will be called when:
    59 	 *  - Another plugin requests it
    60 	 *  - Someone types "meta list", it will show up as "REFUSED"
    61 	 *  - When Metamod need to re-check the plugin's status
    62 	 *  - If the plugin does something like overload a factory, Metamod will make sure the Query() returns true
    63 	 *    before calling it.
    64 	 *  Also note that this query will only override Metamod when the plugin is running and not paused.
    65 	 *
    66 	 * @param error		Buffer for error message.  This can be NULL!
    67 	 * @param maxlen	Maximum length of error buffer.
    68 	 * @return			Status code - true for okay, false for badness.
    69 	 */
    70 	virtual bool QueryRunning(char *error, size_t maxlen)
    71 	{
    72 		return true;
    73 	}
    74 
    75 	/** 
    76 	 * @brief Called on plugin unload.  You can return false if you know your plugin
    77 	 *  is not capable of restoring critical states it modifies.
    78 	 *
    79 	 * @param	error Error message buffer
    80 	 * @param	maxlen Size of error message buffer
    81 	 * @return	True on success, return false to request no unload.
    82 	 */
    83 	virtual bool Unload(char *error, size_t maxlen)
    84 	{
    85 		return true;
    86 	}
    87 
    88 	/** @brief Called on plugin pause.
    89 	 *
    90 	 * @param	error Error message buffer
    91 	 * @param	maxlen Size of error message buffer
    92 	 * @return	True on success, return false to request no pause.
    93 	 */
    94 	virtual bool Pause(char *error, size_t maxlen)
    95 	{
    96 		return true;
    97 	}
    98 
    99 	/** @brief Called on plugin unpause.
   100 	 *
   101 	 * @param	error Error message buffer
   102 	 * @param	maxlen Size of error message buffer
   103 	 * @return	True on success, return false to request no unpause.
   104 	 */
   105 	virtual bool Unpause(char *error, size_t maxlen)
   106 	{
   107 		return true;
   108 	}
   109 public:
   110 	/** @brief Return author as string */
   111 	virtual const char *GetAuthor() =0;
   112 
   113 	/** @brief Return plugin name as string */
   114 	virtual const char *GetName() =0;
   115 
   116 	/** @brief Return a description as string */
   117 	virtual const char *GetDescription() =0;
   118 
   119 	/** @brief Return a URL as string */
   120 	virtual const char *GetURL() =0;
   121 
   122 	/** @brief Return quick license code as string */
   123 	virtual const char *GetLicense() =0;
   124 
   125 	/** @brief Return version as string */
   126 	virtual const char *GetVersion() =0;
   127 
   128 	/** @brief Return author as string */
   129 	virtual const char *GetDate() =0;
   130 
   131 	/** @brief Return author as string */
   132 	virtual const char *GetLogTag() =0;
   133 public:
   134 	/**
   135 	 * @brief Called when all plugins have been loaded - API version 4
   136 	 *
   137 	 * This is useful for knowing when it's safe to request things another plugin might have.
   138 	 * NOTE for API 7 - This is called after DLLInit(). 
   139 	 */
   140 	virtual void AllPluginsLoaded()
   141 	{
   142 	}
   143 };
   144 
   145 /**
   146  * @brief Added in 1.1 so plugins could listen to specific events
   147  */
   148 class IMetamodListener
   149 {
   150 public:
   151 	virtual ~IMetamodListener() { }
   152 public:
   153 	virtual void OnPluginLoad(PluginId id) { }
   154 
   155 	virtual void OnPluginUnload(PluginId id) { }
   156 
   157 	virtual void OnPluginPause(PluginId id) { }
   158 
   159 	virtual void OnPluginUnpause(PluginId id) { }
   160 
   161 	virtual void OnLevelInit(char const *pMapName, char const *pMapEntities, char const *pOldLevel, char const *pLandmarkName, bool loadGame, bool background) { }
   162 
   163 	virtual void OnLevelShutdown() { }
   164 
   165 	virtual void *OnEngineQuery(const char *iface, int *ret)
   166 	{
   167 		if (ret)
   168 			*ret = IFACE_FAILED;
   169 		return NULL; 
   170 	}
   171 
   172 	virtual void *OnPhysicsQuery(const char *iface, int *ret)
   173 	{
   174 		if (ret)
   175 			*ret = IFACE_FAILED;
   176 		return NULL; 
   177 	}
   178 
   179 	virtual void *OnFileSystemQuery(const char *iface, int *ret)
   180 	{
   181 		if (ret)
   182 			*ret = IFACE_FAILED;
   183 		return NULL; 
   184 	}
   185 
   186 	virtual void *OnGameDLLQuery(const char *iface, int *ret)
   187 	{
   188 		if (ret)
   189 			*ret = IFACE_FAILED;
   190 		return NULL; 
   191 	}
   192 
   193 	virtual void *OnMetamodQuery(const char *iface, int *ret)
   194 	{
   195 		if (ret)
   196 			*ret = IFACE_FAILED;
   197 		return NULL; 	
   198 	}
   199 };
   200 
   201 #define PL_EXPOSURE		CreateInterface
   202 #define PL_EXPOSURE_C	"CreateInterface"
   203 
   204 #define PLUGIN_EXPOSE(name, var) \
   205 	ISmmAPI *g_SMAPI = NULL; \
   206 	ISmmPlugin *g_PLAPI = NULL; \
   207 	PluginId g_PLID = (PluginId)0; \
   208 	SourceHook::ISourceHook *g_SHPtr = NULL; \
   209 	SMM_API void *PL_EXPOSURE(const char *name, int *code) { \
   210 		if (name && !strcmp(name, PLAPI_NAME)) { \
   211 			return static_cast<void *>(&var); \
   212 		} \
   213 		return NULL; \
   214 	}
   215 
   216 #define PLUGIN_GLOBALVARS()	\
   217 	extern SourceHook::ISourceHook *g_SHPtr; \
   218 	extern ISmmAPI *g_SMAPI; \
   219 	extern ISmmPlugin *g_PLAPI; \
   220 	extern PluginId g_PLID; 
   221 
   222 #define PLUGIN_SAVEVARS() \
   223 	g_SMAPI = ismm; \
   224 	g_SHPtr = static_cast<SourceHook::ISourceHook *>(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \
   225 	g_PLAPI = static_cast<ISmmPlugin *>(this); \
   226 	g_PLID = id;
   227 
   228 #define META_LOG				g_SMAPI->LogMsg
   229 #define META_REGCMD(name)		g_SMAPI->RegisterConCmdBase(g_PLAPI, name##_command)
   230 #define META_REGCVAR(var)		g_SMAPI->RegisterConCmdBase(g_PLAPI, var)
   231 #define META_UNREGCMD(name)		g_SMAPI->UnregisterConCmdBase(g_PLAPI, name##_command)
   232 #define META_UNREGCVAR(var)		g_SMAPI->UnregisterConCmdBase(g_PLAPI, var)
   233 #define	META_CONPRINT			g_SMAPI->ConPrint
   234 #define META_CONPRINTF			g_SMAPI->ConPrintf
   235 
   236 //probably should use this up above someday
   237 #define CONCMD_VARNAME(name) name##_command
   238 
   239 #if !defined SMM_API
   240 #if defined __WIN32__ || defined _WIN32 || defined WIN32
   241 	#define SMM_API extern "C" __declspec(dllexport)
   242 #elif defined __GNUC__
   243 	#define SMM_API	extern "C"
   244 #endif
   245 #endif //!defined SMM_API
   246 
   247 #endif //_INCLUDE_ISMM_PLUGIN_H