1 /* ======== SourceMM ========
2 * Copyright (C) 2004-2007 Metamod:Source Development Team
3 * No warranties of any kind
7 * Author(s): David "BAILOPAN" Anderson
8 * ============================
11 #ifndef _INCLUDE_ISMM_PLUGIN_H
12 #define _INCLUDE_ISMM_PLUGIN_H
15 * @brief Plugin API interface
19 #include <interface.h>
20 #include <sourcehook/sourcehook.h>
23 #define PLAPI_VERSION 12
24 #define PLAPI_NAME "ISmmPlugin"
31 virtual int GetApiVersion() { return PLAPI_VERSION; }
32 virtual ~ISmmPlugin() { }
35 * @brief Called on plugin load.
37 * NOTE - As of API 7, this is called as DLLInit() executes - after the parameters are known, but before
38 * the original GameDLL function is called. Therefore, you cannot hook it, but you don't need to -
39 * Load() is basically your hook.
40 * NOTE - As of API 7, you can override factories before the engine and gamedll exchange them.
41 * However, take care to note that if your plugin is unloaded, and the gamedll/engine have cached
42 * an interface you've passed, something will definitely crash. Be careful.
44 * @param id Internal id of plugin. Saved globally by PLUGIN_SAVEVARS()
45 * @param ismm External API for SourceMM. Saved globally by PLUGIN_SAVEVARS()
46 * @param list Contains a list of factories. Hook a factory call by setting one equal to your own function.
47 * @param late Set to true if your plugin was loaded late (not at server load).
48 * @param error Error message buffer
49 * @param maxlen Size of error message buffer
50 * @return True if successful, return false to reject the load.
52 virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0;
55 * @brief Called when your plugin is "queried".
57 * This is useful for rejecting a loaded state. For example, if your plugin wants
58 * to stop operating, it can simply return false and copy an error message. This
59 * will notify other plugins or MM:S of something bad that happened. NOTE - MM:S
60 * will not cache the return state, so if you return false, your plugin will not
61 * actually be paused or unloaded. This callback will be called when:
62 * - Another plugin requests it
63 * - Someone types "meta list", it will show up as "REFUSED"
64 * - When Metamod need to re-check the plugin's status
65 * - If the plugin does something like overload a factory, Metamod will make sure the Query() returns true
67 * Also note that this query will only override Metamod when the plugin is running and not paused.
69 * @param error Buffer for error message. This can be NULL!
70 * @param maxlen Maximum length of error buffer.
71 * @return Status code - true for okay, false for badness.
73 virtual bool QueryRunning(char *error, size_t maxlen)
79 * @brief Called on plugin unload. You can return false if you know your plugin
80 * is not capable of restoring critical states it modifies.
82 * @param error Error message buffer
83 * @param maxlen Size of error message buffer
84 * @return True on success, return false to request no unload.
86 virtual bool Unload(char *error, size_t maxlen)
91 /** @brief Called on plugin pause.
93 * @param error Error message buffer
94 * @param maxlen Size of error message buffer
95 * @return True on success, return false to request no pause.
97 virtual bool Pause(char *error, size_t maxlen)
102 /** @brief Called on plugin unpause.
104 * @param error Error message buffer
105 * @param maxlen Size of error message buffer
106 * @return True on success, return false to request no unpause.
108 virtual bool Unpause(char *error, size_t maxlen)
113 /** @brief Return author as string */
114 virtual const char *GetAuthor() =0;
116 /** @brief Return plugin name as string */
117 virtual const char *GetName() =0;
119 /** @brief Return a description as string */
120 virtual const char *GetDescription() =0;
122 /** @brief Return a URL as string */
123 virtual const char *GetURL() =0;
125 /** @brief Return quick license code as string */
126 virtual const char *GetLicense() =0;
128 /** @brief Return version as string */
129 virtual const char *GetVersion() =0;
131 /** @brief Return author as string */
132 virtual const char *GetDate() =0;
134 /** @brief Return author as string */
135 virtual const char *GetLogTag() =0;
138 * @brief Called when all plugins have been loaded.
140 * This is called after DLLInit(), and thus the mod has been mostly initialized.
141 * It is also safe to assume that all other (automatically loaded) plugins are now
142 * ready to start interacting, because they are all loaded.
144 virtual void AllPluginsLoaded()
150 * @brief Added in 1.1 so plugins could listen to specific events
152 class IMetamodListener
155 virtual ~IMetamodListener()
160 * @brief Called when a plugin is loaded.
162 * @param id Id of the plugin.
164 virtual void OnPluginLoad(PluginId id)
169 * @brief Called when a plugin is unloaded.
171 * @param id Id of the plugin.
173 virtual void OnPluginUnload(PluginId id)
178 * @brief Called when a plugin is paused.
180 * @param id Id of the plugin.
182 virtual void OnPluginPause(PluginId id)
187 * @brief Called when a plugin is unpaused.
189 * @param id Id of the plugin.
191 virtual void OnPluginUnpause(PluginId id)
196 * @brief Called when the level is loaded (after GameInit, before ServerActivate).
198 * To override this, hook IServerGameDLL::LevelInit().
200 * @param pMapName Name of the map.
201 * @param pMapEntities Lump string of the map entities, in KeyValue format.
202 * @param pOldLevel Unknown.
203 * @param pLandmarkName Unknown.
204 * @param loadGame Unknown.
205 * @param background Unknown.
207 virtual void OnLevelInit(char const *pMapName, char const *pMapEntities, char const *pOldLevel, char const *pLandmarkName, bool loadGame, bool background) { }
210 * @brief Called when the level is shut down. May be called more than once.
212 virtual void OnLevelShutdown()
217 * @brief Called when engineFactory() is used through Metamod:Source's wrapper.
218 * This can be used to provide interfaces to other plugins or the GameDLL.
220 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
222 * @param iface Interface string.
223 * @param ret Optional pointer to store return code.
224 * @return Generic pointer to the interface, or NULL if not found.
226 virtual void *OnEngineQuery(const char *iface, int *ret)
237 * @brief Called when the physics factory is used through Metamod:Source's wrapper.
238 * This can be used to provide interfaces to other plugins.
240 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
242 * @param iface Interface string.
243 * @param ret Optional pointer to store return code.
244 * @return Generic pointer to the interface, or NULL if not found.
246 virtual void *OnPhysicsQuery(const char *iface, int *ret)
257 * @brief Called when the filesystem factory is used through Metamod:Source's wrapper.
258 * This can be used to provide interfaces to other plugins.
260 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
262 * @param iface Interface string.
263 * @param ret Optional pointer to store return code.
264 * @return Generic pointer to the interface, or NULL if not found.
266 virtual void *OnFileSystemQuery(const char *iface, int *ret)
277 * @brief Called when the server DLL's factory is used through Metamod:Source's wrapper.
278 * This can be used to provide interfaces to other plugins.
280 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
282 * @param iface Interface string.
283 * @param ret Optional pointer to store return code.
284 * @return Generic pointer to the interface, or NULL if not found.
286 virtual void *OnGameDLLQuery(const char *iface, int *ret)
297 * @brief Called when Metamod's own factory is invoked.
298 * This can be used to provide interfaces to other plugins.
300 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
302 * @param iface Interface string.
303 * @param ret Optional pointer to store return code.
304 * @return Generic pointer to the interface, or NULL if not found.
306 virtual void *OnMetamodQuery(const char *iface, int *ret)
317 * @brief Called when Metamod:Source acquires a valid IServerPluginCallbacks
318 * pointer to be used for hooking by plugins.
320 * This will only be called after a call to ISmmAPI::EnableVSPListener().
321 * If called before GameInit, this callback will occur before LevelInit.
322 * Otherwise, it will be called on the first call after that.
324 * This callback is provided to all plugins regardless of which (or how many)
325 * called EnableVSPListener(), but only if at least one did in fact enable it.
327 * This callback is only available for plugins using API v1:5 (Metamod:Source 1.4+).
328 * If a plugin loads lately, it may still call EnableVSPListener().
330 * @param iface Interface pointer. If NULL, then the VSP listening construct
331 * failed to initialize and is not available.
333 virtual void OnVSPListening(IServerPluginCallbacks *iface)
338 * @brief Called when Metamod:Source is about to remove a concommand or convar.
339 * This can also be called if ISmmAPI::UnregisterConCmdBase is used by a plugin.
341 * @param id Id of the plugin that created the concommand or convar.
342 * @param pCommand Pointer to concommand or convar that is being removed.
344 virtual void OnUnlinkConCommandBase(PluginId id, ConCommandBase *pCommand)
349 #define PL_EXPOSURE CreateInterface
350 #define PL_EXPOSURE_C "CreateInterface"
352 #define PLUGIN_EXPOSE(name, var) \
353 ISmmAPI *g_SMAPI = NULL; \
354 ISmmPlugin *g_PLAPI = NULL; \
355 PluginId g_PLID = (PluginId)0; \
356 SourceHook::ISourceHook *g_SHPtr = NULL; \
357 SMM_API void *PL_EXPOSURE(const char *name, int *code) { \
358 if (name && !strcmp(name, PLAPI_NAME)) { \
359 return static_cast<void *>(&var); \
364 #define PLUGIN_GLOBALVARS() \
365 extern SourceHook::ISourceHook *g_SHPtr; \
366 extern ISmmAPI *g_SMAPI; \
367 extern ISmmPlugin *g_PLAPI; \
368 extern PluginId g_PLID;
370 #define PLUGIN_SAVEVARS() \
372 g_SHPtr = static_cast<SourceHook::ISourceHook *>(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \
373 g_PLAPI = static_cast<ISmmPlugin *>(this); \
376 #define META_LOG g_SMAPI->LogMsg
377 #define META_REGCMD(name) g_SMAPI->RegisterConCmdBase(g_PLAPI, name##_command)
378 #define META_REGCVAR(var) g_SMAPI->RegisterConCmdBase(g_PLAPI, var)
379 #define META_UNREGCMD(name) g_SMAPI->UnregisterConCmdBase(g_PLAPI, name##_command)
380 #define META_UNREGCVAR(var) g_SMAPI->UnregisterConCmdBase(g_PLAPI, var)
381 #define META_CONPRINT g_SMAPI->ConPrint
382 #define META_CONPRINTF g_SMAPI->ConPrintf
384 /* Probably should use this up above someday */
385 #define CONCMD_VARNAME(name) name##_command
388 #if defined __WIN32__ || defined _WIN32 || defined WIN32
389 #define SMM_API extern "C" __declspec(dllexport)
390 #elif defined __GNUC__
391 #if (__GNUC__ == 4) && (__GNUC_MINOR__ >= 1)
392 #define SMM_API extern "C" __attribute__ ((visibility("default")))
394 #define SMM_API extern "C"
397 #endif //!defined SMM_API
400 * @brief Macro for automatically getting a current or newer Valve interface.
402 * @param v_factory Factory method to use from ISmmAPI (such as engineFactory).
403 * @param v_var Variable name to store into.
404 * @param v_type Interface type (do not include the pointer/asterisk).
405 * @param v_name Interface name.
407 #define GET_V_IFACE_CURRENT(v_factory, v_var, v_type, v_name) \
408 v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name); \
411 if (error && maxlen) \
413 snprintf(error, maxlen, "Could not find interface: %s", v_name); \
419 * @brief Same as GET_V_IFACE, except searches for any.
421 * @param v_factory Factory method to use from ISmmAPI (such as engineFactory).
422 * @param v_var Variable name to store into.
423 * @param v_type Interface type (do not include the pointer/asterisk).
424 * @param v_name Interface name.
426 #define GET_V_IFACE_ANY(v_factory, v_var, v_type, v_name) \
427 v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name, 0); \
430 if (error && maxlen) \
432 snprintf(error, maxlen, "Could not find interface: %s", v_name); \
437 #endif //_INCLUDE_ISMM_PLUGIN_H