sourcemm/ISmmPlugin.h
branchsourcemm-1.6.0
changeset 347 e82968c21606
child 348 716af2e7be78
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/sourcemm/ISmmPlugin.h	Tue Sep 18 20:03:47 2007 +0000
     1.3 @@ -0,0 +1,409 @@
     1.4 +/* ======== SourceMM ========
     1.5 +* Copyright (C) 2004-2007 Metamod:Source Development Team
     1.6 +* No warranties of any kind
     1.7 +*
     1.8 +* License: zlib/libpng
     1.9 +*
    1.10 +* Author(s): David "BAILOPAN" Anderson
    1.11 +* ============================
    1.12 +*/
    1.13 +
    1.14 +#ifndef _INCLUDE_ISMM_PLUGIN_H
    1.15 +#define _INCLUDE_ISMM_PLUGIN_H
    1.16 +
    1.17 +/**
    1.18 + * @brief Plugin API interface
    1.19 + * @file ISmmPlugin.h
    1.20 + */
    1.21 +
    1.22 +#include <interface.h>
    1.23 +#include <sourcehook/sourcehook.h>
    1.24 +#include "ISmmAPI.h"
    1.25 +
    1.26 +#define PLAPI_VERSION	10
    1.27 +#define PLAPI_NAME		"ISmmPlugin"
    1.28 +
    1.29 +class ISmmAPI;
    1.30 +
    1.31 +class ISmmPlugin
    1.32 +{
    1.33 +public:
    1.34 +	virtual int GetApiVersion() { return PLAPI_VERSION; }
    1.35 +	virtual ~ISmmPlugin() { }
    1.36 +public:
    1.37 +	/**
    1.38 +	 * @brief Called on plugin load.
    1.39 +	 * NOTE - As of API 7, this is called as DLLInit() executes - after the parameters are known, but before 
    1.40 +	 *  the original GameDLL function is called.  Therefore, you cannot hook it, but you don't need to - 
    1.41 +	 *  Load() is basically your hook.
    1.42 +	 * NOTE - As of API 7, you can override factories before the engine and gamedll exchange them.
    1.43 +	 *  However, take care to note that if your plugin is unloaded, and the gamedll/engine have cached
    1.44 +	 *  an interface you've passed, something will definitely crash.  Be careful.
    1.45 +	 *
    1.46 +	 * @param id	Internal id of plugin.  Saved globally by PLUGIN_SAVEVARS()
    1.47 +	 * @param ismm	External API for SourceMM.  Saved globally by PLUGIN_SAVEVARS()
    1.48 +	 * @param list	Contains a list of factories.  Hook a factory call by setting one equal to your own function.
    1.49 +	 * @param late	Set to true if your plugin was loaded late (not at server load).
    1.50 +	 * @param error Error message buffer
    1.51 +	 * @param maxlen Size of error message buffer
    1.52 +	 * @return		True if successful, return false to reject the load.
    1.53 +	 */
    1.54 +	virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0;
    1.55 +
    1.56 +	/**
    1.57 +	 * @brief Called when your plugin is "queried".  This is useful for rejecting a loaded
    1.58 +	 *  state.  For example, if your plugin wants to stop operating, it can simply return
    1.59 +	 *  false and copy an error message.  This will notify other plugins or MM:S of something
    1.60 +	 *  bad that happened.  NOTE - MM:S will not cache the return state, so if you return false,
    1.61 +	 *  your plugin will not actually be paused or unloaded.  This callback will be called when:
    1.62 +	 *  - Another plugin requests it
    1.63 +	 *  - Someone types "meta list", it will show up as "REFUSED"
    1.64 +	 *  - When Metamod need to re-check the plugin's status
    1.65 +	 *  - If the plugin does something like overload a factory, Metamod will make sure the Query() returns true
    1.66 +	 *    before calling it.
    1.67 +	 *  Also note that this query will only override Metamod when the plugin is running and not paused.
    1.68 +	 *
    1.69 +	 * @param error		Buffer for error message.  This can be NULL!
    1.70 +	 * @param maxlen	Maximum length of error buffer.
    1.71 +	 * @return			Status code - true for okay, false for badness.
    1.72 +	 */
    1.73 +	virtual bool QueryRunning(char *error, size_t maxlen)
    1.74 +	{
    1.75 +		return true;
    1.76 +	}
    1.77 +
    1.78 +	/** 
    1.79 +	 * @brief Called on plugin unload.  You can return false if you know your plugin
    1.80 +	 *  is not capable of restoring critical states it modifies.
    1.81 +	 *
    1.82 +	 * @param error		Error message buffer
    1.83 +	 * @param maxlen	Size of error message buffer
    1.84 +	 * @return			True on success, return false to request no unload.
    1.85 +	 */
    1.86 +	virtual bool Unload(char *error, size_t maxlen)
    1.87 +	{
    1.88 +		return true;
    1.89 +	}
    1.90 +
    1.91 +	/** @brief Called on plugin pause.
    1.92 +	 *
    1.93 +	 * @param	error Error message buffer
    1.94 +	 * @param	maxlen Size of error message buffer
    1.95 +	 * @return	True on success, return false to request no pause.
    1.96 +	 */
    1.97 +	virtual bool Pause(char *error, size_t maxlen)
    1.98 +	{
    1.99 +		return true;
   1.100 +	}
   1.101 +
   1.102 +	/** @brief Called on plugin unpause.
   1.103 +	 *
   1.104 +	 * @param	error Error message buffer
   1.105 +	 * @param	maxlen Size of error message buffer
   1.106 +	 * @return	True on success, return false to request no unpause.
   1.107 +	 */
   1.108 +	virtual bool Unpause(char *error, size_t maxlen)
   1.109 +	{
   1.110 +		return true;
   1.111 +	}
   1.112 +public:
   1.113 +	/** @brief Return author as string */
   1.114 +	virtual const char *GetAuthor() =0;
   1.115 +
   1.116 +	/** @brief Return plugin name as string */
   1.117 +	virtual const char *GetName() =0;
   1.118 +
   1.119 +	/** @brief Return a description as string */
   1.120 +	virtual const char *GetDescription() =0;
   1.121 +
   1.122 +	/** @brief Return a URL as string */
   1.123 +	virtual const char *GetURL() =0;
   1.124 +
   1.125 +	/** @brief Return quick license code as string */
   1.126 +	virtual const char *GetLicense() =0;
   1.127 +
   1.128 +	/** @brief Return version as string */
   1.129 +	virtual const char *GetVersion() =0;
   1.130 +
   1.131 +	/** @brief Return author as string */
   1.132 +	virtual const char *GetDate() =0;
   1.133 +
   1.134 +	/** @brief Return author as string */
   1.135 +	virtual const char *GetLogTag() =0;
   1.136 +public:
   1.137 +	/**
   1.138 +	 * @brief Called when all plugins have been loaded - API version 4
   1.139 +	 *
   1.140 +	 * This is useful for knowing when it's safe to request things another plugin might have.
   1.141 +	 * NOTE for API 7 - This is called after DLLInit(). 
   1.142 +	 */
   1.143 +	virtual void AllPluginsLoaded()
   1.144 +	{
   1.145 +	}
   1.146 +};
   1.147 +
   1.148 +/**
   1.149 + * @brief Added in 1.1 so plugins could listen to specific events
   1.150 + */
   1.151 +class IMetamodListener
   1.152 +{
   1.153 +public:
   1.154 +	virtual ~IMetamodListener() { }
   1.155 +public:
   1.156 +	/**
   1.157 +	 * @brief Called when a plugin is loaded.
   1.158 +	 *
   1.159 +	 * @param id		Id of the plugin.
   1.160 +	 */
   1.161 +	virtual void OnPluginLoad(PluginId id) { }
   1.162 +
   1.163 +	/**
   1.164 +	 * @brief Called when a plugin is unloaded.
   1.165 +	 *
   1.166 +	 * @param id		Id of the plugin.
   1.167 +	 */
   1.168 +	virtual void OnPluginUnload(PluginId id) { }
   1.169 +
   1.170 +	/**
   1.171 +	 * @brief Called when a plugin is paused.
   1.172 +	 *
   1.173 +	 * @param id		Id of the plugin.
   1.174 +	 */
   1.175 +	virtual void OnPluginPause(PluginId id) { }
   1.176 +
   1.177 +	/**
   1.178 +	 * @brief Called when a plugin is unpaused.
   1.179 +	 *
   1.180 +	 * @param id		Id of the plugin.
   1.181 +	 */
   1.182 +	virtual void OnPluginUnpause(PluginId id) { }
   1.183 +
   1.184 +	/**
   1.185 +	 * @brief Called when the level is loaded (after GameInit, before ServerActivate).
   1.186 +	 *
   1.187 +	 * To override this, hook IServerGameDLL::LevelInit().
   1.188 +	 *
   1.189 +	 * @param pMapName		Name of the map.
   1.190 +	 * @param pMapEntities	Lump string of the map entities, in KeyValue format.
   1.191 +	 * @param pOldLevel		Unknown.
   1.192 +	 * @param pLandmarkName	Unknown.
   1.193 +	 * @param loadGame		Unknown.
   1.194 +	 * @param background	Unknown.
   1.195 +	 */
   1.196 +	virtual void OnLevelInit(char const *pMapName, char const *pMapEntities, char const *pOldLevel, char const *pLandmarkName, bool loadGame, bool background) { }
   1.197 +
   1.198 +	/**
   1.199 +	 * @brief Called when the level is shut down.  May be called more than once.
   1.200 +	 */
   1.201 +	virtual void OnLevelShutdown() { }
   1.202 +
   1.203 +	/**
   1.204 +	 * @brief Called when engineFactory() is used through Metamod:Source's wrapper.
   1.205 +	 * This can be used to provide interfaces to other plugins or the GameDLL.
   1.206 +	 *
   1.207 +	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   1.208 +	 *
   1.209 +	 * @param iface			Interface string.
   1.210 +	 * @param ret			Optional pointer to store return code.
   1.211 +	 * @return				Generic pointer to the interface, or NULL if not found.
   1.212 +	 */
   1.213 +	virtual void *OnEngineQuery(const char *iface, int *ret)
   1.214 +	{
   1.215 +		if (ret)
   1.216 +		{
   1.217 +			*ret = IFACE_FAILED;
   1.218 +		}
   1.219 +
   1.220 +		return NULL; 
   1.221 +	}
   1.222 +
   1.223 +	/**
   1.224 +	 * @brief Called when the physics factory is used through Metamod:Source's wrapper.
   1.225 +	 * This can be used to provide interfaces to other plugins.
   1.226 +	 *
   1.227 +	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   1.228 +	 *
   1.229 +	 * @param iface			Interface string.
   1.230 +	 * @param ret			Optional pointer to store return code.
   1.231 +	 * @return				Generic pointer to the interface, or NULL if not found.
   1.232 +	 */
   1.233 +	virtual void *OnPhysicsQuery(const char *iface, int *ret)
   1.234 +	{
   1.235 +		if (ret)
   1.236 +		{
   1.237 +			*ret = IFACE_FAILED;
   1.238 +		}
   1.239 +
   1.240 +		return NULL; 
   1.241 +	}
   1.242 +
   1.243 +	/**
   1.244 +	 * @brief Called when the filesystem factory is used through Metamod:Source's wrapper.
   1.245 +	 * This can be used to provide interfaces to other plugins.
   1.246 +	 *
   1.247 +	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   1.248 +	 *
   1.249 +	 * @param iface			Interface string.
   1.250 +	 * @param ret			Optional pointer to store return code.
   1.251 +	 * @return				Generic pointer to the interface, or NULL if not found.
   1.252 +	 */
   1.253 +	virtual void *OnFileSystemQuery(const char *iface, int *ret)
   1.254 +	{
   1.255 +		if (ret)
   1.256 +		{
   1.257 +			*ret = IFACE_FAILED;
   1.258 +		}
   1.259 +		
   1.260 +		return NULL; 
   1.261 +	}
   1.262 +
   1.263 +	/**
   1.264 +	 * @brief Called when the server DLL's factory is used through Metamod:Source's wrapper.
   1.265 +	 * This can be used to provide interfaces to other plugins.
   1.266 +	 *
   1.267 +	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   1.268 +	 *
   1.269 +	 * @param iface			Interface string.
   1.270 +	 * @param ret			Optional pointer to store return code.
   1.271 +	 * @return				Generic pointer to the interface, or NULL if not found.
   1.272 +	 */
   1.273 +	virtual void *OnGameDLLQuery(const char *iface, int *ret)
   1.274 +	{
   1.275 +		if (ret)
   1.276 +		{
   1.277 +			*ret = IFACE_FAILED;
   1.278 +		}
   1.279 +
   1.280 +		return NULL; 
   1.281 +	}
   1.282 +
   1.283 +	/**
   1.284 +	 * @brief Called when Metamod's own factory is invoked.  
   1.285 +	 * This can be used to provide interfaces to other plugins.
   1.286 +	 *
   1.287 +	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   1.288 +	 *
   1.289 +	 * @param iface			Interface string.
   1.290 +	 * @param ret			Optional pointer to store return code.
   1.291 +	 * @return				Generic pointer to the interface, or NULL if not found.
   1.292 +	 */
   1.293 +	virtual void *OnMetamodQuery(const char *iface, int *ret)
   1.294 +	{
   1.295 +		if (ret)
   1.296 +		{
   1.297 +			*ret = IFACE_FAILED;
   1.298 +		}
   1.299 +
   1.300 +		return NULL; 	
   1.301 +	}
   1.302 +
   1.303 +	/**
   1.304 +	 * @brief Called when Metamod:Source acquires a valid IServerPluginCallbacks 
   1.305 +	 * pointer to be used for hooking by plugins.
   1.306 +	 *
   1.307 +	 * This will only be called after a call to ISmmAPI::EnableVSPListener().
   1.308 +	 * If called before GameInit, this callback will occur before LevelInit.
   1.309 +	 * Otherwise, it will be called on the first call after that.
   1.310 +	 *
   1.311 +	 * This callback is provided to all plugins regardless of which (or how many)
   1.312 +	 * called EnableVSPListener(), but only if at least one did in fact enable it.
   1.313 +	 *
   1.314 +	 * This callback is only available for plugins using API v1:5 (SourceMM 1.4+).
   1.315 +	 *
   1.316 +	 * @param iface			Interface pointer.  If NULL, then the VSP listening construct
   1.317 +	 *						failed to initialize and is not available.
   1.318 +	 */
   1.319 +	virtual void OnVSPListening(IServerPluginCallbacks *iface)
   1.320 +	{
   1.321 +	}
   1.322 +};
   1.323 +
   1.324 +#define PL_EXPOSURE		CreateInterface
   1.325 +#define PL_EXPOSURE_C	"CreateInterface"
   1.326 +
   1.327 +#define PLUGIN_EXPOSE(name, var) \
   1.328 +	ISmmAPI *g_SMAPI = NULL; \
   1.329 +	ISmmPlugin *g_PLAPI = NULL; \
   1.330 +	PluginId g_PLID = (PluginId)0; \
   1.331 +	SourceHook::ISourceHook *g_SHPtr = NULL; \
   1.332 +	SMM_API void *PL_EXPOSURE(const char *name, int *code) { \
   1.333 +		if (name && !strcmp(name, PLAPI_NAME)) { \
   1.334 +			return static_cast<void *>(&var); \
   1.335 +		} \
   1.336 +		return NULL; \
   1.337 +	}
   1.338 +
   1.339 +#define PLUGIN_GLOBALVARS()	\
   1.340 +	extern SourceHook::ISourceHook *g_SHPtr; \
   1.341 +	extern ISmmAPI *g_SMAPI; \
   1.342 +	extern ISmmPlugin *g_PLAPI; \
   1.343 +	extern PluginId g_PLID; 
   1.344 +
   1.345 +#define PLUGIN_SAVEVARS() \
   1.346 +	g_SMAPI = ismm; \
   1.347 +	g_SHPtr = static_cast<SourceHook::ISourceHook *>(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \
   1.348 +	g_PLAPI = static_cast<ISmmPlugin *>(this); \
   1.349 +	g_PLID = id;
   1.350 +
   1.351 +#define META_LOG				g_SMAPI->LogMsg
   1.352 +#define META_REGCMD(name)		g_SMAPI->RegisterConCmdBase(g_PLAPI, name##_command)
   1.353 +#define META_REGCVAR(var)		g_SMAPI->RegisterConCmdBase(g_PLAPI, var)
   1.354 +#define META_UNREGCMD(name)		g_SMAPI->UnregisterConCmdBase(g_PLAPI, name##_command)
   1.355 +#define META_UNREGCVAR(var)		g_SMAPI->UnregisterConCmdBase(g_PLAPI, var)
   1.356 +#define	META_CONPRINT			g_SMAPI->ConPrint
   1.357 +#define META_CONPRINTF			g_SMAPI->ConPrintf
   1.358 +
   1.359 +/* Probably should use this up above someday */
   1.360 +#define CONCMD_VARNAME(name) name##_command
   1.361 +
   1.362 +#if !defined SMM_API
   1.363 +#if defined __WIN32__ || defined _WIN32 || defined WIN32
   1.364 +	#define SMM_API extern "C" __declspec(dllexport)
   1.365 +#elif defined __GNUC__
   1.366 +	#if (__GNUC__ == 4) && (__GNUC_MINOR__ >= 1)
   1.367 +		#define SMM_API extern "C" __attribute__ ((visibility("default")))	
   1.368 +	#else
   1.369 +		#define SMM_API	extern "C" 
   1.370 +	#endif	
   1.371 +#endif
   1.372 +#endif //!defined SMM_API
   1.373 +
   1.374 +/**
   1.375 + * @brief Macro for automatically getting a current or newer Valve interface.
   1.376 + *
   1.377 + * @param v_factory		Factory method to use from ISmmAPI (such as engineFactory).
   1.378 + * @param v_var			Variable name to store into.
   1.379 + * @param v_type		Interface type (do not include the pointer/asterisk).
   1.380 + * @param v_name		Interface name.
   1.381 + */
   1.382 +#define GET_V_IFACE_CURRENT(v_factory, v_var, v_type, v_name) \
   1.383 +	v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name); \
   1.384 +	if (!v_var) \
   1.385 +	{ \
   1.386 +		if (error && maxlen) \
   1.387 +		{ \
   1.388 +			snprintf(error, maxlen, "Could not find interface: %s", v_name); \
   1.389 +		} \
   1.390 +		return false; \
   1.391 +	}
   1.392 +
   1.393 + /**
   1.394 +  * @brief Same as GET_V_IFACE, except searches for any.
   1.395 +  *
   1.396 +  * @param v_factory	Factory method to use from ISmmAPI (such as engineFactory).
   1.397 +  * @param v_var		Variable name to store into.
   1.398 +  * @param v_type		Interface type (do not include the pointer/asterisk).
   1.399 +  * @param v_name		Interface name.
   1.400 +  */
   1.401 +#define GET_V_IFACE_ANY(v_factory, v_var, v_type, v_name) \
   1.402 +	v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name, 0); \
   1.403 +	if (!v_var) \
   1.404 +	{ \
   1.405 +		if (error && maxlen) \
   1.406 +		{ \
   1.407 +			snprintf(error, maxlen, "Could not find interface: %s", v_name); \
   1.408 +		} \
   1.409 +		return false; \
   1.410 +	}
   1.411 +
   1.412 +#endif //_INCLUDE_ISMM_PLUGIN_H