3 * ======================================================
5 * Copyright (C) 2004-2008 AlliedModders LLC and authors.
7 * ======================================================
9 * This software is provided 'as-is', without any express or implied warranty.
10 * In no event will the authors be held liable for any damages arising from
11 * the use of this software.
13 * Permission is granted to anyone to use this software for any purpose,
14 * including commercial applications, and to alter it and redistribute it
15 * freely, subject to the following restrictions:
17 * 1. The origin of this software must not be misrepresented; you must not
18 * claim that you wrote the original software. If you use this software in a
19 * product, an acknowledgment in the product documentation would be
20 * appreciated but is not required.
21 * 2. Altered source versions must be plainly marked as such, and must not be
22 * misrepresented as being the original software.
23 * 3. This notice may not be removed or altered from any source distribution.
28 #ifndef _INCLUDE_ISMM_PLUGIN_H
29 #define _INCLUDE_ISMM_PLUGIN_H
32 * @brief Plugin API interface.
33 * @file ISmmPlugin.h These are callbacks that plugins can implement without hooks.
34 * The pure-virtual ISmmPlugin callbacks must be implemented for the load to load.
37 #include <sourcehook.h>
38 #include <IPluginManager.h>
40 #include <ISmmPluginExt.h>
47 * @brief Callbacks that a plugin must expose.
53 * @brief Called to request the plugin's API version.
55 * This is the first callback invoked, and always remains at the top
56 * of the virtual table.
58 * @return Plugin API version.
60 virtual int GetApiVersion()
62 return METAMOD_PLAPI_VERSION;
66 * @brief Virtual destructor so GCC doesn't complain.
74 * @brief Called on plugin load.
76 * This is called as DLLInit() executes - after the parameters are
77 * known, but before the original GameDLL function is called.
78 * Therefore, you cannot hook it, but you don't need to - Load() is
79 * basically your hook. You can override factories before the engine
80 * and gamedll exchange them. However, take care to note that if your
81 * plugin is unloaded, and the gamedll/engine have cached an interface
82 * you've passed, something will definitely crash. Be careful.
84 * @param id Internal id of plugin. Saved globally by PLUGIN_SAVEVARS()
85 * @param ismm External API for SourceMM. Saved globally by PLUGIN_SAVEVARS()
86 * @param error Error message buffer
87 * @param maxlength Size of error message buffer
88 * @param late Set to true if your plugin was loaded late (not at server load).
89 * @return True if successful, return false to reject the load.
91 virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0;
94 * @brief Called when all plugins have been loaded.
96 * This is called after DLLInit(), and thus the mod has been mostly initialized.
97 * It is also safe to assume that all other (automatically loaded) plugins are now
98 * ready to start interacting, because they are all loaded.
100 virtual void AllPluginsLoaded()
105 * @brief Called when your plugin is "queried".
107 * This is useful for rejecting a loaded state. For example, if your
108 * plugin wants to stop operating, it can simply return false and copy
109 * an error message. This will notify other plugins or MM:S of
110 * something bad that happened. MM:S will not cache the return state,
111 * so if you return false, your plugin will not actually be paused or
112 * unloaded. This callback will be called when:
113 * - Another plugin requests it
114 * - Someone types "meta list", it will show up as "REFUSED"
115 * - When Metamod need to re-check the plugin's status
116 * - If the plugin does something like overload a factory, Metamod
117 * will make sure the Query() returns true before calling it.
118 * Also note that this query will only override Metamod when the
119 * plugin is running and not paused.
121 * @param error Buffer for error message, or NULL if none.
122 * @param maxlen Maximum length of error buffer.
123 * @return Status code - true for okay, false for badness.
125 virtual bool QueryRunning(char *error, size_t maxlen)
131 * @brief Called on plugin unload. You can return false if you know
132 * your plugin is not capable of restoring critical states it modifies.
134 * @param error Error message buffer
135 * @param maxlen Size of error message buffer
136 * @return True on success, return false to request no unload.
138 virtual bool Unload(char *error, size_t maxlen)
144 * @brief Called on plugin pause.
146 * @param error Error message buffer
147 * @param maxlen Size of error message buffer
148 * @return True on success, return false to request no pause.
150 virtual bool Pause(char *error, size_t maxlen)
156 * @brief Called on plugin unpause.
158 * @param error Error message buffer
159 * @param maxlen Size of error message buffer
160 * @return True on success, return false to request no unpause.
162 virtual bool Unpause(char *error, size_t maxlen)
167 /** @brief Return author as string */
168 virtual const char *GetAuthor() =0;
170 /** @brief Return plugin name as string */
171 virtual const char *GetName() =0;
173 /** @brief Return a description as string */
174 virtual const char *GetDescription() =0;
176 /** @brief Return a URL as string */
177 virtual const char *GetURL() =0;
179 /** @brief Return quick license code as string */
180 virtual const char *GetLicense() =0;
182 /** @brief Return version as string */
183 virtual const char *GetVersion() =0;
185 /** @brief Return author as string */
186 virtual const char *GetDate() =0;
188 /** @brief Return author as string */
189 virtual const char *GetLogTag() =0;
193 * @brief Various events that Metamod can fire.
195 class IMetamodListener
199 * @brief Called when a plugin is loaded.
201 * @param id Id of the plugin.
203 virtual void OnPluginLoad(PluginId id)
208 * @brief Called when a plugin is unloaded.
210 * @param id Id of the plugin.
212 virtual void OnPluginUnload(PluginId id)
217 * @brief Called when a plugin is paused.
219 * @param id Id of the plugin.
221 virtual void OnPluginPause(PluginId id)
226 * @brief Called when a plugin is unpaused.
228 * @param id Id of the plugin.
230 virtual void OnPluginUnpause(PluginId id)
235 * @brief Called when the level is loaded (after GameInit, before
238 * To override this, hook IServerGameDLL::LevelInit().
240 * @param pMapName Name of the map.
241 * @param pMapEntities Lump string of the map entities, in KeyValues
243 * @param pOldLevel Unknown.
244 * @param pLandmarkName Unknown.
245 * @param loadGame Unknown.
246 * @param background Unknown.
248 virtual void OnLevelInit(char const *pMapName,
249 char const *pMapEntities,
250 char const *pOldLevel,
251 char const *pLandmarkName,
258 * @brief Called when the level is shut down. May be called more than
261 virtual void OnLevelShutdown()
266 * @brief Called when engineFactory() is used through Metamod:Source's
267 * wrapper. This can be used to provide interfaces to other plugins or
270 * If ret is passed, you should fill it with META_IFACE_OK or META_IFACE_FAILED.
272 * @param iface Interface string.
273 * @param ret Optional pointer to store return code.
274 * @return Generic pointer to the interface, or NULL if
277 virtual void *OnEngineQuery(const char *iface, int *ret)
281 *ret = META_IFACE_FAILED;
288 * @brief Called when the physics factory is used through
289 * Metamod:Source's wrapper. This can be used to provide interfaces to
292 * If ret is passed, you should fill it with META_IFACE_OK or META_IFACE_FAILED.
294 * @param iface Interface string.
295 * @param ret Optional pointer to store return code.
296 * @return Generic pointer to the interface, or NULL if
299 virtual void *OnPhysicsQuery(const char *iface, int *ret)
303 *ret = META_IFACE_FAILED;
310 * @brief Called when the filesystem factory is used through
311 * Metamod:Source's wrapper. This can be used to provide interfaces to
314 * If ret is passed, you should fill it with META_IFACE_OK or META_IFACE_FAILED.
316 * @param iface Interface string.
317 * @param ret Optional pointer to store return code.
318 * @return Generic pointer to the interface, or NULL if not
321 virtual void *OnFileSystemQuery(const char *iface, int *ret)
325 *ret = META_IFACE_FAILED;
332 * @brief Called when the server DLL's factory is used through
333 * Metamod:Source's wrapper. This can be used to provide interfaces to
336 * If ret is passed, you should fill it with META_IFACE_OK or META_IFACE_FAILED.
338 * @param iface Interface string.
339 * @param ret Optional pointer to store return code.
340 * @return Generic pointer to the interface, or NULL if not
343 virtual void *OnGameDLLQuery(const char *iface, int *ret)
347 *ret = META_IFACE_FAILED;
354 * @brief Called when Metamod's own factory is invoked.
355 * This can be used to provide interfaces to other plugins.
357 * If ret is passed, you should fill it with META_IFACE_OK or META_IFACE_FAILED.
359 * @param iface Interface string.
360 * @param ret Optional pointer to store return code.
361 * @return Generic pointer to the interface, or NULL if not
364 virtual void *OnMetamodQuery(const char *iface, int *ret)
368 *ret = META_IFACE_FAILED;
375 * @brief Called when Metamod:Source acquires a valid
376 * IServerPluginCallbacks pointer to be used for hooking by plugins.
378 * This will only be called after a call to ISmmAPI::EnableVSPListener().
379 * If called before GameInit, this callback will occur before LevelInit.
380 * Otherwise, it will be called on the first call after that.
382 * This callback is provided to all plugins regardless of which (or how
383 * many) called EnableVSPListener(), but only if at least one did in
384 * fact enable it, and only once for all plugins. That is, a late
385 * loading plugin should use ISmmAPI::GetVSPInfo() before relying on
388 * This callback is never called if Metamod:Source is in VSP mode.
389 * If in VSP mode, a VSP instance is automatically and always available
390 * via ISmmAPI::GetVSPInfo(), which should be called anyway (to handle
391 * late loading cases).
393 * @param iface Interface pointer. If NULL, then the VSP
394 * listening construct failed to initialize and
397 virtual void OnVSPListening(IServerPluginCallbacks *iface)
402 * @brief Called when Metamod:Source is about to remove a concommand or
403 * convar. This can also be called if ISmmAPI::UnregisterConCmdBase is
406 * @param id Id of the plugin that created the concommand or
408 * @param pCommand Pointer to concommand or convar that is being
411 virtual void OnUnlinkConCommandBase(PluginId id, ConCommandBase *pCommand)
417 #if !defined METAMOD_NO_AUTO_NAMESPACE
418 using namespace SourceMM;
421 #define PL_EXPOSURE CreateInterface
422 #define PL_EXPOSURE_C "CreateInterface"
425 * @brief Exposes the plugin to the MM:S loader.
427 * @param name Deprecated - should be a variable name (like name).
428 * @param var Name of the variable that contains the singleton.
429 * This macro automatically takes the address of it, so
430 * you should not pass a pointer to your plugin's
433 #define PLUGIN_EXPOSE(name, var) \
434 ISmmAPI *g_SMAPI = NULL; \
435 ISmmPlugin *g_PLAPI = NULL; \
436 PluginId g_PLID = (PluginId)0; \
437 SourceHook::ISourceHook *g_SHPtr = NULL; \
438 SMM_API void *PL_EXPOSURE(const char *name, int *code) { \
439 if (name && !strcmp(name, METAMOD_PLAPI_NAME)) { \
440 return static_cast<void *>(&var); \
447 * @brief This should be in one of your header files, if you wish
448 * to use values like g_SHPtr in other files.
450 #define PLUGIN_GLOBALVARS() \
451 extern SourceHook::ISourceHook *g_SHPtr; \
452 extern ISmmAPI *g_SMAPI; \
453 extern ISmmPlugin *g_PLAPI; \
454 extern PluginId g_PLID;
457 * @brief This should be the first line in your Load callback.
459 #define PLUGIN_SAVEVARS() \
461 g_SHPtr = static_cast<SourceHook::ISourceHook *>(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \
462 g_PLAPI = static_cast<ISmmPlugin *>(this); \
465 #define META_LOG g_SMAPI->LogMsg
466 #define META_REGCMD(name) g_SMAPI->RegisterConCommandBase(g_PLAPI, name##_command)
467 #define META_REGCVAR(var) g_SMAPI->RegisterConCommandBase(g_PLAPI, var)
468 #define META_UNREGCMD(name) g_SMAPI->UnregisterConCommandBase(g_PLAPI, name##_command)
469 #define META_UNREGCVAR(var) g_SMAPI->UnregisterConCommandBase(g_PLAPI, var)
470 #define META_CONPRINT g_SMAPI->ConPrint
471 #define META_CONPRINTF g_SMAPI->ConPrintf
473 /* Probably should use this up above someday */
474 #define CONCMD_VARNAME(name) name##_command
477 #if defined __WIN32__ || defined _WIN32 || defined WIN32
478 #define SMM_API extern "C" __declspec(dllexport)
479 #elif defined __GNUC__
480 #if (__GNUC__ == 4) && (__GNUC_MINOR__ >= 1)
481 #define SMM_API extern "C" __attribute__ ((visibility("default")))
483 #define SMM_API extern "C"
486 #endif //!defined SMM_API
489 * @brief Macro for automatically getting a current or newer Valve interface.
491 * @param v_factory Factory method to use from ISmmAPI (such as engineFactory).
492 * @param v_var Variable name to store into.
493 * @param v_type Interface type (do not include the pointer/asterisk).
494 * @param v_name Interface name.
496 #define GET_V_IFACE_CURRENT(v_factory, v_var, v_type, v_name) \
497 v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name); \
500 if (error && maxlen) \
502 ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
508 * @brief Same as GET_V_IFACE, except searches for any.
510 * @param v_factory Factory method to use from ISmmAPI (such as engineFactory).
511 * @param v_var Variable name to store into.
512 * @param v_type Interface type (do not include the pointer/asterisk).
513 * @param v_name Interface name.
515 #define GET_V_IFACE_ANY(v_factory, v_var, v_type, v_name) \
516 v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name, 0); \
519 if (error && maxlen) \
521 ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
526 #endif //_INCLUDE_ISMM_PLUGIN_H