1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/core/ISmmPlugin.h Fri Nov 14 04:04:02 2008 -0600
1.3 @@ -0,0 +1,528 @@
1.4 +/*
1.5 + * vim: set ts=4 :
1.6 + * ======================================================
1.7 + * Metamod:Source
1.8 + * Copyright (C) 2004-2008 AlliedModders LLC and authors.
1.9 + * All rights reserved.
1.10 + * ======================================================
1.11 + *
1.12 + * This software is provided 'as-is', without any express or implied warranty.
1.13 + * In no event will the authors be held liable for any damages arising from
1.14 + * the use of this software.
1.15 + *
1.16 + * Permission is granted to anyone to use this software for any purpose,
1.17 + * including commercial applications, and to alter it and redistribute it
1.18 + * freely, subject to the following restrictions:
1.19 + *
1.20 + * 1. The origin of this software must not be misrepresented; you must not
1.21 + * claim that you wrote the original software. If you use this software in a
1.22 + * product, an acknowledgment in the product documentation would be
1.23 + * appreciated but is not required.
1.24 + * 2. Altered source versions must be plainly marked as such, and must not be
1.25 + * misrepresented as being the original software.
1.26 + * 3. This notice may not be removed or altered from any source distribution.
1.27 + *
1.28 + * Version: $Id$
1.29 + */
1.30 +
1.31 +#ifndef _INCLUDE_ISMM_PLUGIN_H
1.32 +#define _INCLUDE_ISMM_PLUGIN_H
1.33 +
1.34 +/**
1.35 + * @brief Plugin API interface.
1.36 + * @file ISmmPlugin.h These are callbacks that plugins can implement without hooks.
1.37 + * The pure-virtual ISmmPlugin callbacks must be implemented for the load to load.
1.38 + */
1.39 +
1.40 +#include <interface.h>
1.41 +#include <sourcehook.h>
1.42 +#include <IPluginManager.h>
1.43 +#include <ISmmAPI.h>
1.44 +#include <ISmmPluginExt.h>
1.45 +
1.46 +namespace SourceMM
1.47 +{
1.48 + class ISmmAPI;
1.49 +
1.50 + /**
1.51 + * @brief Callbacks that a plugin must expose.
1.52 + */
1.53 + class ISmmPlugin
1.54 + {
1.55 + public:
1.56 + /**
1.57 + * @brief Called to request the plugin's API version.
1.58 + *
1.59 + * This is the first callback invoked, and always remains at the top
1.60 + * of the virtual table.
1.61 + *
1.62 + * @return Plugin API version.
1.63 + */
1.64 + virtual int GetApiVersion()
1.65 + {
1.66 + return METAMOD_PLAPI_VERSION;
1.67 + }
1.68 +
1.69 + /**
1.70 + * @brief Virtual destructor so GCC doesn't complain.
1.71 + */
1.72 + virtual ~ISmmPlugin()
1.73 + {
1.74 + }
1.75 +
1.76 + public:
1.77 + /**
1.78 + * @brief Called on plugin load.
1.79 + *
1.80 + * This is called as DLLInit() executes - after the parameters are
1.81 + * known, but before the original GameDLL function is called.
1.82 + * Therefore, you cannot hook it, but you don't need to - Load() is
1.83 + * basically your hook. You can override factories before the engine
1.84 + * and gamedll exchange them. However, take care to note that if your
1.85 + * plugin is unloaded, and the gamedll/engine have cached an interface
1.86 + * you've passed, something will definitely crash. Be careful.
1.87 + *
1.88 + * @param id Internal id of plugin. Saved globally by PLUGIN_SAVEVARS()
1.89 + * @param ismm External API for SourceMM. Saved globally by PLUGIN_SAVEVARS()
1.90 + * @param error Error message buffer
1.91 + * @param maxlength Size of error message buffer
1.92 + * @param late Set to true if your plugin was loaded late (not at server load).
1.93 + * @return True if successful, return false to reject the load.
1.94 + */
1.95 + virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0;
1.96 +
1.97 + /**
1.98 + * @brief Called when all plugins have been loaded.
1.99 + *
1.100 + * This is called after DLLInit(), and thus the mod has been mostly initialized.
1.101 + * It is also safe to assume that all other (automatically loaded) plugins are now
1.102 + * ready to start interacting, because they are all loaded.
1.103 + */
1.104 + virtual void AllPluginsLoaded()
1.105 + {
1.106 + }
1.107 +
1.108 + /**
1.109 + * @brief Called when your plugin is "queried".
1.110 + *
1.111 + * This is useful for rejecting a loaded state. For example, if your
1.112 + * plugin wants to stop operating, it can simply return false and copy
1.113 + * an error message. This will notify other plugins or MM:S of
1.114 + * something bad that happened. MM:S will not cache the return state,
1.115 + * so if you return false, your plugin will not actually be paused or
1.116 + * unloaded. This callback will be called when:
1.117 + * - Another plugin requests it
1.118 + * - Someone types "meta list", it will show up as "REFUSED"
1.119 + * - When Metamod need to re-check the plugin's status
1.120 + * - If the plugin does something like overload a factory, Metamod
1.121 + * will make sure the Query() returns true before calling it.
1.122 + * Also note that this query will only override Metamod when the
1.123 + * plugin is running and not paused.
1.124 + *
1.125 + * @param error Buffer for error message, or NULL if none.
1.126 + * @param maxlen Maximum length of error buffer.
1.127 + * @return Status code - true for okay, false for badness.
1.128 + */
1.129 + virtual bool QueryRunning(char *error, size_t maxlen)
1.130 + {
1.131 + return true;
1.132 + }
1.133 +
1.134 + /**
1.135 + * @brief Called on plugin unload. You can return false if you know
1.136 + * your plugin is not capable of restoring critical states it modifies.
1.137 + *
1.138 + * @param error Error message buffer
1.139 + * @param maxlen Size of error message buffer
1.140 + * @return True on success, return false to request no unload.
1.141 + */
1.142 + virtual bool Unload(char *error, size_t maxlen)
1.143 + {
1.144 + return true;
1.145 + }
1.146 +
1.147 + /**
1.148 + * @brief Called on plugin pause.
1.149 + *
1.150 + * @param error Error message buffer
1.151 + * @param maxlen Size of error message buffer
1.152 + * @return True on success, return false to request no pause.
1.153 + */
1.154 + virtual bool Pause(char *error, size_t maxlen)
1.155 + {
1.156 + return true;
1.157 + }
1.158 +
1.159 + /**
1.160 + * @brief Called on plugin unpause.
1.161 + *
1.162 + * @param error Error message buffer
1.163 + * @param maxlen Size of error message buffer
1.164 + * @return True on success, return false to request no unpause.
1.165 + */
1.166 + virtual bool Unpause(char *error, size_t maxlen)
1.167 + {
1.168 + return true;
1.169 + }
1.170 + public:
1.171 + /** @brief Return author as string */
1.172 + virtual const char *GetAuthor() =0;
1.173 +
1.174 + /** @brief Return plugin name as string */
1.175 + virtual const char *GetName() =0;
1.176 +
1.177 + /** @brief Return a description as string */
1.178 + virtual const char *GetDescription() =0;
1.179 +
1.180 + /** @brief Return a URL as string */
1.181 + virtual const char *GetURL() =0;
1.182 +
1.183 + /** @brief Return quick license code as string */
1.184 + virtual const char *GetLicense() =0;
1.185 +
1.186 + /** @brief Return version as string */
1.187 + virtual const char *GetVersion() =0;
1.188 +
1.189 + /** @brief Return author as string */
1.190 + virtual const char *GetDate() =0;
1.191 +
1.192 + /** @brief Return author as string */
1.193 + virtual const char *GetLogTag() =0;
1.194 + };
1.195 +
1.196 + /**
1.197 + * @brief Various events that Metamod can fire.
1.198 + */
1.199 + class IMetamodListener
1.200 + {
1.201 + public:
1.202 + /**
1.203 + * @brief Called when a plugin is loaded.
1.204 + *
1.205 + * @param id Id of the plugin.
1.206 + */
1.207 + virtual void OnPluginLoad(PluginId id)
1.208 + {
1.209 + }
1.210 +
1.211 + /**
1.212 + * @brief Called when a plugin is unloaded.
1.213 + *
1.214 + * @param id Id of the plugin.
1.215 + */
1.216 + virtual void OnPluginUnload(PluginId id)
1.217 + {
1.218 + }
1.219 +
1.220 + /**
1.221 + * @brief Called when a plugin is paused.
1.222 + *
1.223 + * @param id Id of the plugin.
1.224 + */
1.225 + virtual void OnPluginPause(PluginId id)
1.226 + {
1.227 + }
1.228 +
1.229 + /**
1.230 + * @brief Called when a plugin is unpaused.
1.231 + *
1.232 + * @param id Id of the plugin.
1.233 + */
1.234 + virtual void OnPluginUnpause(PluginId id)
1.235 + {
1.236 + }
1.237 +
1.238 + /**
1.239 + * @brief Called when the level is loaded (after GameInit, before
1.240 + * ServerActivate).
1.241 + *
1.242 + * To override this, hook IServerGameDLL::LevelInit().
1.243 + *
1.244 + * @param pMapName Name of the map.
1.245 + * @param pMapEntities Lump string of the map entities, in KeyValues
1.246 + * format.
1.247 + * @param pOldLevel Unknown.
1.248 + * @param pLandmarkName Unknown.
1.249 + * @param loadGame Unknown.
1.250 + * @param background Unknown.
1.251 + */
1.252 + virtual void OnLevelInit(char const *pMapName,
1.253 + char const *pMapEntities,
1.254 + char const *pOldLevel,
1.255 + char const *pLandmarkName,
1.256 + bool loadGame,
1.257 + bool background)
1.258 + {
1.259 + }
1.260 +
1.261 + /**
1.262 + * @brief Called when the level is shut down. May be called more than
1.263 + * once.
1.264 + */
1.265 + virtual void OnLevelShutdown()
1.266 + {
1.267 + }
1.268 +
1.269 + /**
1.270 + * @brief Called when engineFactory() is used through Metamod:Source's
1.271 + * wrapper. This can be used to provide interfaces to other plugins or
1.272 + * the GameDLL.
1.273 + *
1.274 + * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
1.275 + *
1.276 + * @param iface Interface string.
1.277 + * @param ret Optional pointer to store return code.
1.278 + * @return Generic pointer to the interface, or NULL if
1.279 + * not found.
1.280 + */
1.281 + virtual void *OnEngineQuery(const char *iface, int *ret)
1.282 + {
1.283 + if (ret)
1.284 + {
1.285 + *ret = IFACE_FAILED;
1.286 + }
1.287 +
1.288 + return NULL;
1.289 + }
1.290 +
1.291 + /**
1.292 + * @brief Called when the physics factory is used through
1.293 + * Metamod:Source's wrapper. This can be used to provide interfaces to
1.294 + * other plugins.
1.295 + *
1.296 + * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
1.297 + *
1.298 + * @param iface Interface string.
1.299 + * @param ret Optional pointer to store return code.
1.300 + * @return Generic pointer to the interface, or NULL if
1.301 + * not found.
1.302 + */
1.303 + virtual void *OnPhysicsQuery(const char *iface, int *ret)
1.304 + {
1.305 + if (ret)
1.306 + {
1.307 + *ret = IFACE_FAILED;
1.308 + }
1.309 +
1.310 + return NULL;
1.311 + }
1.312 +
1.313 + /**
1.314 + * @brief Called when the filesystem factory is used through
1.315 + * Metamod:Source's wrapper. This can be used to provide interfaces to
1.316 + * other plugins.
1.317 + *
1.318 + * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
1.319 + *
1.320 + * @param iface Interface string.
1.321 + * @param ret Optional pointer to store return code.
1.322 + * @return Generic pointer to the interface, or NULL if not
1.323 + * found.
1.324 + */
1.325 + virtual void *OnFileSystemQuery(const char *iface, int *ret)
1.326 + {
1.327 + if (ret)
1.328 + {
1.329 + *ret = IFACE_FAILED;
1.330 + }
1.331 +
1.332 + return NULL;
1.333 + }
1.334 +
1.335 + /**
1.336 + * @brief Called when the server DLL's factory is used through
1.337 + * Metamod:Source's wrapper. This can be used to provide interfaces to
1.338 + * other plugins.
1.339 + *
1.340 + * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
1.341 + *
1.342 + * @param iface Interface string.
1.343 + * @param ret Optional pointer to store return code.
1.344 + * @return Generic pointer to the interface, or NULL if not
1.345 + * found.
1.346 + */
1.347 + virtual void *OnGameDLLQuery(const char *iface, int *ret)
1.348 + {
1.349 + if (ret)
1.350 + {
1.351 + *ret = IFACE_FAILED;
1.352 + }
1.353 +
1.354 + return NULL;
1.355 + }
1.356 +
1.357 + /**
1.358 + * @brief Called when Metamod's own factory is invoked.
1.359 + * This can be used to provide interfaces to other plugins.
1.360 + *
1.361 + * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
1.362 + *
1.363 + * @param iface Interface string.
1.364 + * @param ret Optional pointer to store return code.
1.365 + * @return Generic pointer to the interface, or NULL if not
1.366 + * found.
1.367 + */
1.368 + virtual void *OnMetamodQuery(const char *iface, int *ret)
1.369 + {
1.370 + if (ret)
1.371 + {
1.372 + *ret = IFACE_FAILED;
1.373 + }
1.374 +
1.375 + return NULL;
1.376 + }
1.377 +
1.378 + /**
1.379 + * @brief Called when Metamod:Source acquires a valid
1.380 + * IServerPluginCallbacks pointer to be used for hooking by plugins.
1.381 + *
1.382 + * This will only be called after a call to ISmmAPI::EnableVSPListener().
1.383 + * If called before GameInit, this callback will occur before LevelInit.
1.384 + * Otherwise, it will be called on the first call after that.
1.385 + *
1.386 + * This callback is provided to all plugins regardless of which (or how
1.387 + * many) called EnableVSPListener(), but only if at least one did in
1.388 + * fact enable it, and only once for all plugins. That is, a late
1.389 + * loading plugin should use ISmmAPI::GetVSPInfo() before relying on
1.390 + * this callback.
1.391 + *
1.392 + * This callback is never called if Metamod:Source is in VSP mode.
1.393 + * If in VSP mode, a VSP instance is automatically and always available
1.394 + * via ISmmAPI::GetVSPInfo(), which should be called anyway (to handle
1.395 + * late loading cases).
1.396 + *
1.397 + * @param iface Interface pointer. If NULL, then the VSP
1.398 + * listening construct failed to initialize and
1.399 + * is not available.
1.400 + */
1.401 + virtual void OnVSPListening(IServerPluginCallbacks *iface)
1.402 + {
1.403 + }
1.404 +
1.405 + /**
1.406 + * @brief Called when Metamod:Source is about to remove a concommand or
1.407 + * convar. This can also be called if ISmmAPI::UnregisterConCmdBase is
1.408 + * used by a plugin.
1.409 + *
1.410 + * @param id Id of the plugin that created the concommand or
1.411 + * convar.
1.412 + * @param pCommand Pointer to concommand or convar that is being
1.413 + * removed.
1.414 + */
1.415 + virtual void OnUnlinkConCommandBase(PluginId id, ConCommandBase *pCommand)
1.416 + {
1.417 + }
1.418 + };
1.419 +}
1.420 +
1.421 +#if !defined METAMOD_NO_AUTO_NAMESPACE
1.422 +using namespace SourceMM;
1.423 +#endif
1.424 +
1.425 +#define PL_EXPOSURE CreateInterface
1.426 +#define PL_EXPOSURE_C "CreateInterface"
1.427 +
1.428 +/**
1.429 + * @brief Exposes the plugin to the MM:S loader.
1.430 + *
1.431 + * @param name Deprecated - should be a variable name (like name).
1.432 + * @param var Name of the variable that contains the singleton.
1.433 + * This macro automatically takes the address of it, so
1.434 + * you should not pass a pointer to your plugin's
1.435 + * singleton.
1.436 + */
1.437 +#define PLUGIN_EXPOSE(name, var) \
1.438 + ISmmAPI *g_SMAPI = NULL; \
1.439 + ISmmPlugin *g_PLAPI = NULL; \
1.440 + PluginId g_PLID = (PluginId)0; \
1.441 + SourceHook::ISourceHook *g_SHPtr = NULL; \
1.442 + SMM_API void *PL_EXPOSURE(const char *name, int *code) { \
1.443 + if (name && !strcmp(name, METAMOD_PLAPI_NAME)) { \
1.444 + return static_cast<void *>(&var); \
1.445 + } \
1.446 + return NULL; \
1.447 + }
1.448 +
1.449 +
1.450 +/**
1.451 + * @brief This should be in one of your header files, if you wish
1.452 + * to use values like g_SHPtr in other files.
1.453 + */
1.454 +#define PLUGIN_GLOBALVARS() \
1.455 + extern SourceHook::ISourceHook *g_SHPtr; \
1.456 + extern ISmmAPI *g_SMAPI; \
1.457 + extern ISmmPlugin *g_PLAPI; \
1.458 + extern PluginId g_PLID;
1.459 +
1.460 +/**
1.461 + * @brief This should be the first line in your Load callback.
1.462 + */
1.463 +#define PLUGIN_SAVEVARS() \
1.464 + g_SMAPI = ismm; \
1.465 + g_SHPtr = static_cast<SourceHook::ISourceHook *>(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \
1.466 + g_PLAPI = static_cast<ISmmPlugin *>(this); \
1.467 + g_PLID = id;
1.468 +
1.469 +#define META_LOG g_SMAPI->LogMsg
1.470 +#define META_REGCMD(name) g_SMAPI->RegisterConCommandBase(g_PLAPI, name##_command)
1.471 +#define META_REGCVAR(var) g_SMAPI->RegisterConCommandBase(g_PLAPI, var)
1.472 +#define META_UNREGCMD(name) g_SMAPI->UnregisterConCommandBase(g_PLAPI, name##_command)
1.473 +#define META_UNREGCVAR(var) g_SMAPI->UnregisterConCommandBase(g_PLAPI, var)
1.474 +#define META_CONPRINT g_SMAPI->ConPrint
1.475 +#define META_CONPRINTF g_SMAPI->ConPrintf
1.476 +
1.477 +/* Probably should use this up above someday */
1.478 +#define CONCMD_VARNAME(name) name##_command
1.479 +
1.480 +#if !defined SMM_API
1.481 +#if defined __WIN32__ || defined _WIN32 || defined WIN32
1.482 + #define SMM_API extern "C" __declspec(dllexport)
1.483 +#elif defined __GNUC__
1.484 + #if (__GNUC__ == 4) && (__GNUC_MINOR__ >= 1)
1.485 + #define SMM_API extern "C" __attribute__ ((visibility("default")))
1.486 + #else
1.487 + #define SMM_API extern "C"
1.488 + #endif
1.489 +#endif
1.490 +#endif //!defined SMM_API
1.491 +
1.492 +/**
1.493 + * @brief Macro for automatically getting a current or newer Valve interface.
1.494 + *
1.495 + * @param v_factory Factory method to use from ISmmAPI (such as engineFactory).
1.496 + * @param v_var Variable name to store into.
1.497 + * @param v_type Interface type (do not include the pointer/asterisk).
1.498 + * @param v_name Interface name.
1.499 + */
1.500 +#define GET_V_IFACE_CURRENT(v_factory, v_var, v_type, v_name) \
1.501 + v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name); \
1.502 + if (!v_var) \
1.503 + { \
1.504 + if (error && maxlen) \
1.505 + { \
1.506 + ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
1.507 + } \
1.508 + return false; \
1.509 + }
1.510 +
1.511 + /**
1.512 + * @brief Same as GET_V_IFACE, except searches for any.
1.513 + *
1.514 + * @param v_factory Factory method to use from ISmmAPI (such as engineFactory).
1.515 + * @param v_var Variable name to store into.
1.516 + * @param v_type Interface type (do not include the pointer/asterisk).
1.517 + * @param v_name Interface name.
1.518 + */
1.519 +#define GET_V_IFACE_ANY(v_factory, v_var, v_type, v_name) \
1.520 + v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name, 0); \
1.521 + if (!v_var) \
1.522 + { \
1.523 + if (error && maxlen) \
1.524 + { \
1.525 + ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
1.526 + } \
1.527 + return false; \
1.528 + }
1.529 +
1.530 +#endif //_INCLUDE_ISMM_PLUGIN_H
1.531 +