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