1 /* ======== SourceMM ========
2 * Copyright (C) 2004-2006 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 9
24 #define PLAPI_NAME "ISmmPlugin"
31 virtual int GetApiVersion() { return PLAPI_VERSION; }
32 virtual ~ISmmPlugin() { }
35 * @brief Called on plugin load.
36 * NOTE - As of API 7, this is called as DLLInit() executes - after the parameters are known, but before
37 * the original GameDLL function is called. Therefore, you cannot hook it, but you don't need to -
38 * Load() is basically your hook.
39 * NOTE - As of API 7, you can override factories before the engine and gamedll exchange them.
40 * However, take care to note that if your plugin is unloaded, and the gamedll/engine have cached
41 * an interface you've passed, something will definitely crash. Be careful.
43 * @param id Internal id of plugin. Saved globally by PLUGIN_SAVEVARS()
44 * @param ismm External API for SourceMM. Saved globally by PLUGIN_SAVEVARS()
45 * @param list Contains a list of factories. Hook a factory call by setting one equal to your own function.
46 * @param late Set to true if your plugin was loaded late (not at server load).
47 * @param error Error message buffer
48 * @param maxlen Size of error message buffer
49 * @return True if successful, return false to reject the load.
51 virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0;
54 * @brief Called when your plugin is "queried". This is useful for rejecting a loaded
55 * state. For example, if your plugin wants to stop operating, it can simply return
56 * false and copy an error message. This will notify other plugins or MM:S of something
57 * bad that happened. NOTE - MM:S will not cache the return state, so if you return false,
58 * your plugin will not actually be paused or unloaded. This callback will be called when:
59 * - Another plugin requests it
60 * - Someone types "meta list", it will show up as "REFUSED"
61 * - When Metamod need to re-check the plugin's status
62 * - If the plugin does something like overload a factory, Metamod will make sure the Query() returns true
64 * Also note that this query will only override Metamod when the plugin is running and not paused.
66 * @param error Buffer for error message. This can be NULL!
67 * @param maxlen Maximum length of error buffer.
68 * @return Status code - true for okay, false for badness.
70 virtual bool QueryRunning(char *error, size_t maxlen)
76 * @brief Called on plugin unload. You can return false if you know your plugin
77 * is not capable of restoring critical states it modifies.
79 * @param error Error message buffer
80 * @param maxlen Size of error message buffer
81 * @return True on success, return false to request no unload.
83 virtual bool Unload(char *error, size_t maxlen)
88 /** @brief Called on plugin pause.
90 * @param error Error message buffer
91 * @param maxlen Size of error message buffer
92 * @return True on success, return false to request no pause.
94 virtual bool Pause(char *error, size_t maxlen)
99 /** @brief Called on plugin unpause.
101 * @param error Error message buffer
102 * @param maxlen Size of error message buffer
103 * @return True on success, return false to request no unpause.
105 virtual bool Unpause(char *error, size_t maxlen)
110 /** @brief Return author as string */
111 virtual const char *GetAuthor() =0;
113 /** @brief Return plugin name as string */
114 virtual const char *GetName() =0;
116 /** @brief Return a description as string */
117 virtual const char *GetDescription() =0;
119 /** @brief Return a URL as string */
120 virtual const char *GetURL() =0;
122 /** @brief Return quick license code as string */
123 virtual const char *GetLicense() =0;
125 /** @brief Return version as string */
126 virtual const char *GetVersion() =0;
128 /** @brief Return author as string */
129 virtual const char *GetDate() =0;
131 /** @brief Return author as string */
132 virtual const char *GetLogTag() =0;
135 * @brief Called when all plugins have been loaded - API version 4
137 * This is useful for knowing when it's safe to request things another plugin might have.
138 * NOTE for API 7 - This is called after DLLInit().
140 virtual void AllPluginsLoaded()
146 * @brief Added in 1.1 so plugins could listen to specific events
148 class IMetamodListener
151 virtual ~IMetamodListener() { }
153 virtual void OnPluginLoad(PluginId id) { }
155 virtual void OnPluginUnload(PluginId id) { }
157 virtual void OnPluginPause(PluginId id) { }
159 virtual void OnPluginUnpause(PluginId id) { }
161 virtual void OnLevelInit(char const *pMapName, char const *pMapEntities, char const *pOldLevel, char const *pLandmarkName, bool loadGame, bool background) { }
163 virtual void OnLevelShutdown() { }
165 virtual void *OnEngineQuery(const char *iface, int *ret)
172 virtual void *OnPhysicsQuery(const char *iface, int *ret)
179 virtual void *OnFileSystemQuery(const char *iface, int *ret)
186 virtual void *OnGameDLLQuery(const char *iface, int *ret)
193 virtual void *OnMetamodQuery(const char *iface, int *ret)
201 #define PL_EXPOSURE CreateInterface
202 #define PL_EXPOSURE_C "CreateInterface"
204 #define PLUGIN_EXPOSE(name, var) \
205 ISmmAPI *g_SMAPI = NULL; \
206 ISmmPlugin *g_PLAPI = NULL; \
207 PluginId g_PLID = (PluginId)0; \
208 SourceHook::ISourceHook *g_SHPtr = NULL; \
209 SMM_API void *PL_EXPOSURE(const char *name, int *code) { \
210 if (name && !strcmp(name, PLAPI_NAME)) { \
211 return static_cast<void *>(&var); \
216 #define PLUGIN_GLOBALVARS() \
217 extern SourceHook::ISourceHook *g_SHPtr; \
218 extern ISmmAPI *g_SMAPI; \
219 extern ISmmPlugin *g_PLAPI; \
220 extern PluginId g_PLID;
222 #define PLUGIN_SAVEVARS() \
224 g_SHPtr = static_cast<SourceHook::ISourceHook *>(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \
225 g_PLAPI = static_cast<ISmmPlugin *>(this); \
228 #define META_LOG g_SMAPI->LogMsg
229 #define META_REGCMD(name) g_SMAPI->RegisterConCmdBase(g_PLAPI, name##_command)
230 #define META_REGCVAR(var) g_SMAPI->RegisterConCmdBase(g_PLAPI, var)
231 #define META_UNREGCMD(name) g_SMAPI->UnregisterConCmdBase(g_PLAPI, name##_command)
232 #define META_UNREGCVAR(var) g_SMAPI->UnregisterConCmdBase(g_PLAPI, var)
233 #define META_CONPRINT g_SMAPI->ConPrint
234 #define META_CONPRINTF g_SMAPI->ConPrintf
236 //probably should use this up above someday
237 #define CONCMD_VARNAME(name) name##_command
240 #if defined __WIN32__ || defined _WIN32 || defined WIN32
241 #define SMM_API extern "C" __declspec(dllexport)
242 #elif defined __GNUC__
243 #if (__GNUC__ == 4) && (__GNUC_MINOR__ >= 1)
244 #define SMM_API extern "C" __attribute__ ((visibility("default")))
246 #define SMM_API extern "C"
249 #endif //!defined SMM_API
252 * @brief Macro for automatically getting a current or newer Valve interface.
254 * @param v_factory Factory method to use from ISmmAPI (such as engineFactory).
255 * @param v_var Variable name to store into.
256 * @param v_type Interface type (do not include the pointer/asterisk).
257 * @param v_name Inteface name.
259 #define GET_V_IFACE_CURRENT(v_factory, v_var, v_type, v_name) \
260 v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name); \
263 if (error && maxlen) \
265 snprintf(error, maxlen, "Could not find interface: %s", v_name); \
271 * @brief Same as GET_V_IFACE, except searches for any.
273 * @param v_factory Factory method to use from ISmmAPI (such as engineFactory).
274 * @param v_var Variable name to store into.
275 * @param v_type Interface type (do not include the pointer/asterisk).
276 * @param v_name Inteface name.
278 #define GET_V_IFACE_ANY(v_factory, v_var, v_type, v_name) \
279 v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name, 0); \
282 if (error && maxlen) \
284 snprintf(error, maxlen, "Could not find interface: %s", v_name); \
290 #endif //_INCLUDE_ISMM_PLUGIN_H