3 * ======================================================
5 * Copyright (C) 2004-2007 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
36 #include <interface.h>
37 #include <sourcehook.h>
38 #include <IPluginManager.h>
41 #define METAMOD_PLAPI_VERSION 13 /**< Version of this header file */
42 #define METAMOD_PLAPI_NAME "ISmmPlugin" /**< Name of the plugin interface */
49 * @brief Callbacks that a plugin must expose.
55 * @brief Called to request the plugin's API version.
57 * This is the first callback invoked, and always remains at the top
58 * of the virtual table.
60 * @return Plugin API version.
62 virtual int GetApiVersion()
64 return METAMOD_PLAPI_VERSION;
68 * @brief Virtual destructor so GCC doesn't complain.
76 * @brief Called on plugin load.
78 * This is called as DLLInit() executes - after the parameters are
79 * known, but before the original GameDLL function is called.
80 * Therefore, you cannot hook it, but you don't need to - Load() is
81 * basically your hook. You can override factories before the engine
82 * and gamedll exchange them. However, take care to note that if your
83 * plugin is unloaded, and the gamedll/engine have cached an interface
84 * you've passed, something will definitely crash. Be careful.
86 * @param id Internal id of plugin. Saved globally by PLUGIN_SAVEVARS()
87 * @param ismm External API for SourceMM. Saved globally by PLUGIN_SAVEVARS()
88 * @param error Error message buffer
89 * @param maxlength Size of error message buffer
90 * @param late Set to true if your plugin was loaded late (not at server load).
91 * @return True if successful, return false to reject the load.
93 virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0;
96 * @brief Called when all plugins have been loaded.
98 * This is called after DLLInit(), and thus the mod has been mostly initialized.
99 * It is also safe to assume that all other (automatically loaded) plugins are now
100 * ready to start interacting, because they are all loaded.
102 virtual void AllPluginsLoaded()
107 * @brief Called when your plugin is "queried".
109 * This is useful for rejecting a loaded state. For example, if your
110 * plugin wants to stop operating, it can simply return false and copy
111 * an error message. This will notify other plugins or MM:S of
112 * something bad that happened. MM:S will not cache the return state,
113 * so if you return false, your plugin will not actually be paused or
114 * unloaded. This callback will be called when:
115 * - Another plugin requests it
116 * - Someone types "meta list", it will show up as "REFUSED"
117 * - When Metamod need to re-check the plugin's status
118 * - If the plugin does something like overload a factory, Metamod
119 * will make sure the Query() returns true before calling it.
120 * Also note that this query will only override Metamod when the
121 * plugin is running and not paused.
123 * @param error Buffer for error message, or NULL if none.
124 * @param maxlen Maximum length of error buffer.
125 * @return Status code - true for okay, false for badness.
127 virtual bool QueryRunning(char *error, size_t maxlen)
133 * @brief Called on plugin unload. You can return false if you know
134 * your plugin is not capable of restoring critical states it modifies.
136 * @param error Error message buffer
137 * @param maxlen Size of error message buffer
138 * @return True on success, return false to request no unload.
140 virtual bool Unload(char *error, size_t maxlen)
146 * @brief Called on plugin pause.
148 * @param error Error message buffer
149 * @param maxlen Size of error message buffer
150 * @return True on success, return false to request no pause.
152 virtual bool Pause(char *error, size_t maxlen)
158 * @brief Called on plugin unpause.
160 * @param error Error message buffer
161 * @param maxlen Size of error message buffer
162 * @return True on success, return false to request no unpause.
164 virtual bool Unpause(char *error, size_t maxlen)
169 /** @brief Return author as string */
170 virtual const char *GetAuthor() =0;
172 /** @brief Return plugin name as string */
173 virtual const char *GetName() =0;
175 /** @brief Return a description as string */
176 virtual const char *GetDescription() =0;
178 /** @brief Return a URL as string */
179 virtual const char *GetURL() =0;
181 /** @brief Return quick license code as string */
182 virtual const char *GetLicense() =0;
184 /** @brief Return version as string */
185 virtual const char *GetVersion() =0;
187 /** @brief Return author as string */
188 virtual const char *GetDate() =0;
190 /** @brief Return author as string */
191 virtual const char *GetLogTag() =0;
195 * @brief Various events that Metamod can fire.
197 class IMetamodListener
201 * @brief Called when a plugin is loaded.
203 * @param id Id of the plugin.
205 virtual void OnPluginLoad(PluginId id)
210 * @brief Called when a plugin is unloaded.
212 * @param id Id of the plugin.
214 virtual void OnPluginUnload(PluginId id)
219 * @brief Called when a plugin is paused.
221 * @param id Id of the plugin.
223 virtual void OnPluginPause(PluginId id)
228 * @brief Called when a plugin is unpaused.
230 * @param id Id of the plugin.
232 virtual void OnPluginUnpause(PluginId id)
237 * @brief Called when the level is loaded (after GameInit, before
240 * To override this, hook IServerGameDLL::LevelInit().
242 * @param pMapName Name of the map.
243 * @param pMapEntities Lump string of the map entities, in KeyValues
245 * @param pOldLevel Unknown.
246 * @param pLandmarkName Unknown.
247 * @param loadGame Unknown.
248 * @param background Unknown.
250 virtual void OnLevelInit(char const *pMapName,
251 char const *pMapEntities,
252 char const *pOldLevel,
253 char const *pLandmarkName,
260 * @brief Called when the level is shut down. May be called more than
263 virtual void OnLevelShutdown()
268 * @brief Called when engineFactory() is used through Metamod:Source's
269 * wrapper. This can be used to provide interfaces to other plugins or
272 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
274 * @param iface Interface string.
275 * @param ret Optional pointer to store return code.
276 * @return Generic pointer to the interface, or NULL if
279 virtual void *OnEngineQuery(const char *iface, int *ret)
290 * @brief Called when the physics factory is used through
291 * Metamod:Source's wrapper. This can be used to provide interfaces to
294 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
296 * @param iface Interface string.
297 * @param ret Optional pointer to store return code.
298 * @return Generic pointer to the interface, or NULL if
301 virtual void *OnPhysicsQuery(const char *iface, int *ret)
312 * @brief Called when the filesystem factory is used through
313 * Metamod:Source's wrapper. This can be used to provide interfaces to
316 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
318 * @param iface Interface string.
319 * @param ret Optional pointer to store return code.
320 * @return Generic pointer to the interface, or NULL if not
323 virtual void *OnFileSystemQuery(const char *iface, int *ret)
334 * @brief Called when the server DLL's factory is used through
335 * Metamod:Source's wrapper. This can be used to provide interfaces to
338 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
340 * @param iface Interface string.
341 * @param ret Optional pointer to store return code.
342 * @return Generic pointer to the interface, or NULL if not
345 virtual void *OnGameDLLQuery(const char *iface, int *ret)
356 * @brief Called when Metamod's own factory is invoked.
357 * This can be used to provide interfaces to other plugins.
359 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
361 * @param iface Interface string.
362 * @param ret Optional pointer to store return code.
363 * @return Generic pointer to the interface, or NULL if not
366 virtual void *OnMetamodQuery(const char *iface, int *ret)
377 * @brief Called when Metamod:Source acquires a valid
378 * IServerPluginCallbacks pointer to be used for hooking by plugins.
380 * This will only be called after a call to ISmmAPI::EnableVSPListener().
381 * If called before GameInit, this callback will occur before LevelInit.
382 * Otherwise, it will be called on the first call after that.
384 * This callback is provided to all plugins regardless of which (or how
385 * many) called EnableVSPListener(), but only if at least one did in
386 * fact enable it, and only once for all plugins. That is, a late
387 * loading plugin should use ISmmAPI::GetVSPInfo() before relying on
390 * @param iface Interface pointer. If NULL, then the VSP
391 * listening construct failed to initialize and
394 virtual void OnVSPListening(IServerPluginCallbacks *iface)
399 * @brief Called when Metamod:Source is about to remove a concommand or
400 * convar. This can also be called if ISmmAPI::UnregisterConCmdBase is
403 * @param id Id of the plugin that created the concommand or
405 * @param pCommand Pointer to concommand or convar that is being
408 virtual void OnUnlinkConCommandBase(PluginId id, ConCommandBase *pCommand)
414 #if !defined METAMOD_NO_AUTO_NAMESPACE
415 using namespace SourceMM;
419 #define PL_EXPOSURE CreateInterface
420 #define PL_EXPOSURE_C "CreateInterface"
422 #define PLUGIN_EXPOSE(name, var) \
423 ISmmAPI *g_SMAPI = NULL; \
424 ISmmPlugin *g_PLAPI = NULL; \
425 PluginId g_PLID = (PluginId)0; \
426 SourceHook::ISourceHook *g_SHPtr = NULL; \
427 SMM_API void *PL_EXPOSURE(const char *name, int *code) { \
428 if (name && !strcmp(name, METAMOD_PLAPI_NAME)) { \
429 return static_cast<void *>(&var); \
434 #define PLUGIN_GLOBALVARS() \
435 extern SourceHook::ISourceHook *g_SHPtr; \
436 extern ISmmAPI *g_SMAPI; \
437 extern ISmmPlugin *g_PLAPI; \
438 extern PluginId g_PLID;
440 #define PLUGIN_SAVEVARS() \
442 g_SHPtr = static_cast<SourceHook::ISourceHook *>(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \
443 g_PLAPI = static_cast<ISmmPlugin *>(this); \
446 #define META_LOG g_SMAPI->LogMsg
447 #define META_REGCMD(name) g_SMAPI->RegisterConCommandBase(g_PLAPI, name##_command)
448 #define META_REGCVAR(var) g_SMAPI->RegisterConCommandBase(g_PLAPI, var)
449 #define META_UNREGCMD(name) g_SMAPI->UnregisterConCommandBase(g_PLAPI, name##_command)
450 #define META_UNREGCVAR(var) g_SMAPI->UnregisterConCommandBase(g_PLAPI, var)
451 #define META_CONPRINT g_SMAPI->ConPrint
452 #define META_CONPRINTF g_SMAPI->ConPrintf
454 /* Probably should use this up above someday */
455 #define CONCMD_VARNAME(name) name##_command
458 #if defined __WIN32__ || defined _WIN32 || defined WIN32
459 #define SMM_API extern "C" __declspec(dllexport)
460 #elif defined __GNUC__
461 #if (__GNUC__ == 4) && (__GNUC_MINOR__ >= 1)
462 #define SMM_API extern "C" __attribute__ ((visibility("default")))
464 #define SMM_API extern "C"
467 #endif //!defined SMM_API
470 * @brief Macro for automatically getting a current or newer Valve interface.
472 * @param v_factory Factory method to use from ISmmAPI (such as engineFactory).
473 * @param v_var Variable name to store into.
474 * @param v_type Interface type (do not include the pointer/asterisk).
475 * @param v_name Interface name.
477 #define GET_V_IFACE_CURRENT(v_factory, v_var, v_type, v_name) \
478 v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name); \
481 if (error && maxlen) \
483 ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
489 * @brief Same as GET_V_IFACE, except searches for any.
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_ANY(v_factory, v_var, v_type, v_name) \
497 v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name, 0); \
500 if (error && maxlen) \
502 ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
507 #endif //_INCLUDE_ISMM_PLUGIN_H