dvander@513: /* dvander@371: * vim: set ts=4 : dvander@371: * ====================================================== dvander@371: * Metamod:Source ds@523: * Copyright (C) 2004-2008 AlliedModders LLC and authors. dvander@371: * All rights reserved. dvander@371: * ====================================================== dvander@371: * dvander@371: * This software is provided 'as-is', without any express or implied warranty. dvander@371: * In no event will the authors be held liable for any damages arising from dvander@371: * the use of this software. dvander@371: * dvander@371: * Permission is granted to anyone to use this software for any purpose, dvander@371: * including commercial applications, and to alter it and redistribute it dvander@371: * freely, subject to the following restrictions: dvander@371: * dvander@371: * 1. The origin of this software must not be misrepresented; you must not dvander@371: * claim that you wrote the original software. If you use this software in a dvander@371: * product, an acknowledgment in the product documentation would be dvander@371: * appreciated but is not required. dvander@371: * 2. Altered source versions must be plainly marked as such, and must not be dvander@371: * misrepresented as being the original software. dvander@371: * 3. This notice may not be removed or altered from any source distribution. dvander@371: * dvander@371: * Version: $Id$ dvander@371: */ dvander@9: dvander@7: #ifndef _INCLUDE_ISMM_PLUGIN_H dvander@7: #define _INCLUDE_ISMM_PLUGIN_H dvander@7: dvander@9: /** dvander@513: * @brief Plugin API interface. dvander@513: * @file ISmmPlugin.h These are callbacks that plugins can implement without hooks. dvander@513: * The pure-virtual ISmmPlugin callbacks must be implemented for the load to load. dvander@9: */ dvander@9: dvander@7: #include dvander@371: #include dvander@396: #include dvander@396: #include dvander@405: #include dvander@7: dvander@396: namespace SourceMM dvander@7: { dvander@396: class ISmmAPI; dvander@7: dvander@122: /** dvander@396: * @brief Callbacks that a plugin must expose. dvander@7: */ dvander@396: class ISmmPlugin dvander@122: { dvander@396: public: dvander@396: /** dvander@396: * @brief Called to request the plugin's API version. dvander@396: * dvander@396: * This is the first callback invoked, and always remains at the top dvander@396: * of the virtual table. dvander@396: * dvander@396: * @return Plugin API version. dvander@396: */ dvander@396: virtual int GetApiVersion() dvander@396: { dvander@396: return METAMOD_PLAPI_VERSION; dvander@396: } dvander@396: dvander@396: /** dvander@396: * @brief Virtual destructor so GCC doesn't complain. dvander@396: */ dvander@396: virtual ~ISmmPlugin() dvander@396: { dvander@396: } dvander@122: dvander@396: public: dvander@396: /** dvander@396: * @brief Called on plugin load. dvander@396: * dvander@396: * This is called as DLLInit() executes - after the parameters are dvander@396: * known, but before the original GameDLL function is called. dvander@396: * Therefore, you cannot hook it, but you don't need to - Load() is dvander@396: * basically your hook. You can override factories before the engine dvander@396: * and gamedll exchange them. However, take care to note that if your dvander@396: * plugin is unloaded, and the gamedll/engine have cached an interface dvander@396: * you've passed, something will definitely crash. Be careful. dvander@396: * dvander@396: * @param id Internal id of plugin. Saved globally by PLUGIN_SAVEVARS() dvander@396: * @param ismm External API for SourceMM. Saved globally by PLUGIN_SAVEVARS() dvander@396: * @param error Error message buffer dvander@396: * @param maxlength Size of error message buffer dvander@396: * @param late Set to true if your plugin was loaded late (not at server load). dvander@396: * @return True if successful, return false to reject the load. dvander@396: */ dvander@396: virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0; dvander@7: dvander@396: /** dvander@396: * @brief Called when all plugins have been loaded. dvander@396: * dvander@396: * This is called after DLLInit(), and thus the mod has been mostly initialized. dvander@396: * It is also safe to assume that all other (automatically loaded) plugins are now dvander@396: * ready to start interacting, because they are all loaded. dvander@396: */ dvander@396: virtual void AllPluginsLoaded() dvander@396: { dvander@396: } dvander@30: dvander@396: /** dvander@396: * @brief Called when your plugin is "queried". dvander@396: * dvander@396: * This is useful for rejecting a loaded state. For example, if your dvander@396: * plugin wants to stop operating, it can simply return false and copy dvander@396: * an error message. This will notify other plugins or MM:S of dvander@396: * something bad that happened. MM:S will not cache the return state, dvander@396: * so if you return false, your plugin will not actually be paused or dvander@396: * unloaded. This callback will be called when: dvander@396: * - Another plugin requests it dvander@396: * - Someone types "meta list", it will show up as "REFUSED" dvander@396: * - When Metamod need to re-check the plugin's status dvander@396: * - If the plugin does something like overload a factory, Metamod dvander@396: * will make sure the Query() returns true before calling it. dvander@396: * Also note that this query will only override Metamod when the dvander@396: * plugin is running and not paused. dvander@396: * dvander@396: * @param error Buffer for error message, or NULL if none. dvander@396: * @param maxlen Maximum length of error buffer. dvander@396: * @return Status code - true for okay, false for badness. dvander@396: */ dvander@396: virtual bool QueryRunning(char *error, size_t maxlen) dvander@396: { dvander@396: return true; dvander@396: } dvander@30: dvander@396: /** dvander@396: * @brief Called on plugin unload. You can return false if you know dvander@396: * your plugin is not capable of restoring critical states it modifies. dvander@396: * dvander@396: * @param error Error message buffer dvander@396: * @param maxlen Size of error message buffer dvander@396: * @return True on success, return false to request no unload. dvander@396: */ dvander@396: virtual bool Unload(char *error, size_t maxlen) dvander@396: { dvander@396: return true; dvander@396: } dvander@30: dvander@396: /** dvander@396: * @brief Called on plugin pause. dvander@396: * dvander@396: * @param error Error message buffer dvander@396: * @param maxlen Size of error message buffer dvander@396: * @return True on success, return false to request no pause. dvander@396: */ dvander@396: virtual bool Pause(char *error, size_t maxlen) dvander@396: { dvander@396: return true; dvander@396: } dvander@7: dvander@396: /** dvander@396: * @brief Called on plugin unpause. dvander@396: * dvander@396: * @param error Error message buffer dvander@396: * @param maxlen Size of error message buffer dvander@396: * @return True on success, return false to request no unpause. dvander@396: */ dvander@396: virtual bool Unpause(char *error, size_t maxlen) dvander@396: { dvander@396: return true; dvander@396: } dvander@396: public: dvander@396: /** @brief Return author as string */ dvander@396: virtual const char *GetAuthor() =0; dvander@396: dvander@396: /** @brief Return plugin name as string */ dvander@396: virtual const char *GetName() =0; dvander@396: dvander@396: /** @brief Return a description as string */ dvander@396: virtual const char *GetDescription() =0; dvander@396: dvander@396: /** @brief Return a URL as string */ dvander@396: virtual const char *GetURL() =0; dvander@396: dvander@396: /** @brief Return quick license code as string */ dvander@396: virtual const char *GetLicense() =0; dvander@396: dvander@396: /** @brief Return version as string */ dvander@396: virtual const char *GetVersion() =0; dvander@396: dvander@396: /** @brief Return author as string */ dvander@396: virtual const char *GetDate() =0; dvander@396: dvander@396: /** @brief Return author as string */ dvander@396: virtual const char *GetLogTag() =0; dvander@396: }; dvander@138: dvander@282: /** dvander@396: * @brief Various events that Metamod can fire. dvander@282: */ dvander@396: class IMetamodListener dvander@371: { dvander@396: public: dvander@396: /** dvander@396: * @brief Called when a plugin is loaded. dvander@396: * dvander@396: * @param id Id of the plugin. dvander@396: */ dvander@396: virtual void OnPluginLoad(PluginId id) dvander@282: { dvander@282: } dvander@282: dvander@396: /** dvander@396: * @brief Called when a plugin is unloaded. dvander@396: * dvander@396: * @param id Id of the plugin. dvander@396: */ dvander@396: virtual void OnPluginUnload(PluginId id) dvander@396: { dvander@396: } dvander@396: dvander@396: /** dvander@396: * @brief Called when a plugin is paused. dvander@396: * dvander@396: * @param id Id of the plugin. dvander@396: */ dvander@396: virtual void OnPluginPause(PluginId id) dvander@396: { dvander@396: } dvander@396: dvander@396: /** dvander@396: * @brief Called when a plugin is unpaused. dvander@396: * dvander@396: * @param id Id of the plugin. dvander@396: */ dvander@396: virtual void OnPluginUnpause(PluginId id) dvander@396: { dvander@396: } dvander@396: dvander@396: /** dvander@396: * @brief Called when the level is loaded (after GameInit, before dvander@396: * ServerActivate). dvander@396: * dvander@396: * To override this, hook IServerGameDLL::LevelInit(). dvander@396: * dvander@396: * @param pMapName Name of the map. dvander@396: * @param pMapEntities Lump string of the map entities, in KeyValues dvander@396: * format. dvander@396: * @param pOldLevel Unknown. dvander@396: * @param pLandmarkName Unknown. dvander@396: * @param loadGame Unknown. dvander@396: * @param background Unknown. dvander@396: */ dvander@396: virtual void OnLevelInit(char const *pMapName, dvander@396: char const *pMapEntities, dvander@396: char const *pOldLevel, dvander@396: char const *pLandmarkName, dvander@396: bool loadGame, dvander@396: bool background) dvander@396: { dvander@396: } dvander@138: dvander@396: /** dvander@396: * @brief Called when the level is shut down. May be called more than dvander@396: * once. dvander@396: */ dvander@396: virtual void OnLevelShutdown() dvander@282: { dvander@396: } dvander@396: dvander@396: /** dvander@396: * @brief Called when engineFactory() is used through Metamod:Source's dvander@396: * wrapper. This can be used to provide interfaces to other plugins or dvander@396: * the GameDLL. dvander@396: * dvander@396: * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED. dvander@396: * dvander@396: * @param iface Interface string. dvander@396: * @param ret Optional pointer to store return code. dvander@396: * @return Generic pointer to the interface, or NULL if dvander@396: * not found. dvander@396: */ dvander@396: virtual void *OnEngineQuery(const char *iface, int *ret) dvander@396: { dvander@396: if (ret) dvander@396: { dvander@396: *ret = IFACE_FAILED; dvander@396: } dvander@396: dvander@396: return NULL; dvander@282: } dvander@282: dvander@396: /** dvander@396: * @brief Called when the physics factory is used through dvander@396: * Metamod:Source's wrapper. This can be used to provide interfaces to dvander@396: * other plugins. dvander@396: * dvander@396: * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED. dvander@396: * dvander@396: * @param iface Interface string. dvander@396: * @param ret Optional pointer to store return code. dvander@396: * @return Generic pointer to the interface, or NULL if dvander@396: * not found. dvander@396: */ dvander@396: virtual void *OnPhysicsQuery(const char *iface, int *ret) dvander@282: { dvander@396: if (ret) dvander@396: { dvander@396: *ret = IFACE_FAILED; dvander@396: } dvander@396: dvander@396: return NULL; dvander@282: } dvander@138: dvander@396: /** dvander@396: * @brief Called when the filesystem factory is used through dvander@396: * Metamod:Source's wrapper. This can be used to provide interfaces to dvander@396: * other plugins. dvander@396: * dvander@396: * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED. dvander@396: * dvander@396: * @param iface Interface string. dvander@396: * @param ret Optional pointer to store return code. dvander@396: * @return Generic pointer to the interface, or NULL if not dvander@396: * found. dvander@396: */ dvander@396: virtual void *OnFileSystemQuery(const char *iface, int *ret) dvander@282: { dvander@396: if (ret) dvander@396: { dvander@396: *ret = IFACE_FAILED; dvander@396: } dvander@396: dvander@396: return NULL; dvander@282: } dvander@282: dvander@396: /** dvander@396: * @brief Called when the server DLL's factory is used through dvander@396: * Metamod:Source's wrapper. This can be used to provide interfaces to dvander@396: * other plugins. dvander@396: * dvander@396: * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED. dvander@396: * dvander@396: * @param iface Interface string. dvander@396: * @param ret Optional pointer to store return code. dvander@396: * @return Generic pointer to the interface, or NULL if not dvander@396: * found. dvander@396: */ dvander@396: virtual void *OnGameDLLQuery(const char *iface, int *ret) dvander@396: { dvander@396: if (ret) dvander@396: { dvander@396: *ret = IFACE_FAILED; dvander@396: } dvander@396: dvander@396: return NULL; dvander@396: } dvander@138: dvander@396: /** dvander@396: * @brief Called when Metamod's own factory is invoked. dvander@396: * This can be used to provide interfaces to other plugins. dvander@396: * dvander@396: * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED. dvander@396: * dvander@396: * @param iface Interface string. dvander@396: * @param ret Optional pointer to store return code. dvander@396: * @return Generic pointer to the interface, or NULL if not dvander@396: * found. dvander@396: */ dvander@396: virtual void *OnMetamodQuery(const char *iface, int *ret) dvander@282: { dvander@396: if (ret) dvander@396: { dvander@396: *ret = IFACE_FAILED; dvander@396: } dvander@396: dvander@396: return NULL; dvander@282: } dvander@282: dvander@396: /** dvander@396: * @brief Called when Metamod:Source acquires a valid dvander@396: * IServerPluginCallbacks pointer to be used for hooking by plugins. dvander@396: * dvander@396: * This will only be called after a call to ISmmAPI::EnableVSPListener(). dvander@396: * If called before GameInit, this callback will occur before LevelInit. dvander@396: * Otherwise, it will be called on the first call after that. dvander@396: * dvander@396: * This callback is provided to all plugins regardless of which (or how dvander@396: * many) called EnableVSPListener(), but only if at least one did in dvander@396: * fact enable it, and only once for all plugins. That is, a late dvander@396: * loading plugin should use ISmmAPI::GetVSPInfo() before relying on dvander@396: * this callback. dvander@396: * dvander@485: * This callback is never called if Metamod:Source is in VSP mode. dvander@485: * If in VSP mode, a VSP instance is automatically and always available dvander@485: * via ISmmAPI::GetVSPInfo(), which should be called anyway (to handle dvander@485: * late loading cases). dvander@485: * dvander@396: * @param iface Interface pointer. If NULL, then the VSP dvander@396: * listening construct failed to initialize and dvander@396: * is not available. dvander@396: */ dvander@396: virtual void OnVSPListening(IServerPluginCallbacks *iface) dvander@396: { dvander@396: } dvander@282: dvander@396: /** dvander@396: * @brief Called when Metamod:Source is about to remove a concommand or dvander@396: * convar. This can also be called if ISmmAPI::UnregisterConCmdBase is dvander@396: * used by a plugin. dvander@396: * dvander@396: * @param id Id of the plugin that created the concommand or dvander@396: * convar. dvander@396: * @param pCommand Pointer to concommand or convar that is being dvander@396: * removed. dvander@396: */ dvander@396: virtual void OnUnlinkConCommandBase(PluginId id, ConCommandBase *pCommand) dvander@396: { dvander@396: } dvander@396: }; dvander@396: } ds@345: dvander@396: #if !defined METAMOD_NO_AUTO_NAMESPACE dvander@396: using namespace SourceMM; dvander@396: #endif dvander@396: dvander@122: #define PL_EXPOSURE CreateInterface dvander@7: #define PL_EXPOSURE_C "CreateInterface" dvander@7: dvander@513: /** dvander@513: * @brief Exposes the plugin to the MM:S loader. dvander@513: * dvander@513: * @param name Deprecated - should be a variable name (like name). dvander@513: * @param var Name of the variable that contains the singleton. dvander@513: * This macro automatically takes the address of it, so dvander@513: * you should not pass a pointer to your plugin's dvander@513: * singleton. dvander@513: */ dvander@7: #define PLUGIN_EXPOSE(name, var) \ dvander@7: ISmmAPI *g_SMAPI = NULL; \ dvander@9: ISmmPlugin *g_PLAPI = NULL; \ dvander@9: PluginId g_PLID = (PluginId)0; \ dvander@7: SourceHook::ISourceHook *g_SHPtr = NULL; \ dvander@7: SMM_API void *PL_EXPOSURE(const char *name, int *code) { \ dvander@396: if (name && !strcmp(name, METAMOD_PLAPI_NAME)) { \ dvander@7: return static_cast(&var); \ dvander@7: } \ dvander@7: return NULL; \ dvander@7: } dvander@7: dvander@513: dvander@513: /** dvander@513: * @brief This should be in one of your header files, if you wish dvander@513: * to use values like g_SHPtr in other files. dvander@513: */ dvander@7: #define PLUGIN_GLOBALVARS() \ dvander@7: extern SourceHook::ISourceHook *g_SHPtr; \ dvander@7: extern ISmmAPI *g_SMAPI; \ dvander@9: extern ISmmPlugin *g_PLAPI; \ dvander@9: extern PluginId g_PLID; dvander@7: dvander@513: /** dvander@513: * @brief This should be the first line in your Load callback. dvander@513: */ dvander@7: #define PLUGIN_SAVEVARS() \ dvander@7: g_SMAPI = ismm; \ dvander@140: g_SHPtr = static_cast(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \ dvander@9: g_PLAPI = static_cast(this); \ dvander@9: g_PLID = id; dvander@7: dvander@122: #define META_LOG g_SMAPI->LogMsg dvander@375: #define META_REGCMD(name) g_SMAPI->RegisterConCommandBase(g_PLAPI, name##_command) dvander@375: #define META_REGCVAR(var) g_SMAPI->RegisterConCommandBase(g_PLAPI, var) dvander@375: #define META_UNREGCMD(name) g_SMAPI->UnregisterConCommandBase(g_PLAPI, name##_command) dvander@375: #define META_UNREGCVAR(var) g_SMAPI->UnregisterConCommandBase(g_PLAPI, var) dvander@122: #define META_CONPRINT g_SMAPI->ConPrint dvander@122: #define META_CONPRINTF g_SMAPI->ConPrintf dvander@7: ds@296: /* Probably should use this up above someday */ ds@66: #define CONCMD_VARNAME(name) name##_command ds@66: dvander@7: #if !defined SMM_API dvander@7: #if defined __WIN32__ || defined _WIN32 || defined WIN32 dvander@7: #define SMM_API extern "C" __declspec(dllexport) dvander@7: #elif defined __GNUC__ dvander@247: #if (__GNUC__ == 4) && (__GNUC_MINOR__ >= 1) dvander@247: #define SMM_API extern "C" __attribute__ ((visibility("default"))) dvander@247: #else dvander@247: #define SMM_API extern "C" dvander@247: #endif dvander@7: #endif dvander@7: #endif //!defined SMM_API dvander@7: dvander@251: /** dvander@251: * @brief Macro for automatically getting a current or newer Valve interface. dvander@251: * dvander@251: * @param v_factory Factory method to use from ISmmAPI (such as engineFactory). dvander@251: * @param v_var Variable name to store into. dvander@251: * @param v_type Interface type (do not include the pointer/asterisk). ds@296: * @param v_name Interface name. dvander@251: */ dvander@251: #define GET_V_IFACE_CURRENT(v_factory, v_var, v_type, v_name) \ dvander@251: v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name); \ dvander@251: if (!v_var) \ dvander@251: { \ dvander@251: if (error && maxlen) \ dvander@251: { \ dvander@376: ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \ dvander@251: } \ dvander@251: return false; \ dvander@251: } dvander@251: dvander@251: /** dvander@251: * @brief Same as GET_V_IFACE, except searches for any. dvander@251: * ds@296: * @param v_factory Factory method to use from ISmmAPI (such as engineFactory). ds@296: * @param v_var Variable name to store into. dvander@251: * @param v_type Interface type (do not include the pointer/asterisk). ds@296: * @param v_name Interface name. dvander@251: */ dvander@251: #define GET_V_IFACE_ANY(v_factory, v_var, v_type, v_name) \ dvander@251: v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name, 0); \ dvander@251: if (!v_var) \ dvander@251: { \ dvander@251: if (error && maxlen) \ dvander@251: { \ dvander@376: ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \ dvander@251: } \ dvander@251: return false; \ dvander@251: } dvander@251: dvander@7: #endif //_INCLUDE_ISMM_PLUGIN_H dvander@371: