sourcemm/ISmmPlugin.h
author David Anderson <dvander@alliedmods.net>
Sat Feb 10 00:31:34 2007 +0000 (2007-02-10)
changeset 282 7a237e9ea5a1
parent 251 3bd7e7008ac3
child 294 0d87bc8606f8
permissions -rw-r--r--
added experimental API for hooking VSP interface calls
updated file license headers
     1 /* ======== SourceMM ========
     2 * Copyright (C) 2004-2006 Metamod:Source Development Team
     3 * No warranties of any kind
     4 *
     5 * License: zlib/libpng
     6 *
     7 * Author(s): David "BAILOPAN" Anderson
     8 * ============================
     9 */
    10 
    11 #ifndef _INCLUDE_ISMM_PLUGIN_H
    12 #define _INCLUDE_ISMM_PLUGIN_H
    13 
    14 /**
    15  * @brief Plugin API interface
    16  * @file ISmmPlugin.h
    17  */
    18 
    19 #include <interface.h>
    20 #include <sourcehook/sourcehook.h>
    21 #include "ISmmAPI.h"
    22 
    23 #define PLAPI_VERSION	10
    24 #define PLAPI_NAME		"ISmmPlugin"
    25 
    26 class ISmmAPI;
    27 
    28 class ISmmPlugin
    29 {
    30 public:
    31 	virtual int GetApiVersion() { return PLAPI_VERSION; }
    32 	virtual ~ISmmPlugin() { }
    33 public:
    34 	/**
    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.
    42 	 *
    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.
    50 	 */
    51 	virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0;
    52 
    53 	/**
    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
    63 	 *    before calling it.
    64 	 *  Also note that this query will only override Metamod when the plugin is running and not paused.
    65 	 *
    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.
    69 	 */
    70 	virtual bool QueryRunning(char *error, size_t maxlen)
    71 	{
    72 		return true;
    73 	}
    74 
    75 	/** 
    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.
    78 	 *
    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.
    82 	 */
    83 	virtual bool Unload(char *error, size_t maxlen)
    84 	{
    85 		return true;
    86 	}
    87 
    88 	/** @brief Called on plugin pause.
    89 	 *
    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.
    93 	 */
    94 	virtual bool Pause(char *error, size_t maxlen)
    95 	{
    96 		return true;
    97 	}
    98 
    99 	/** @brief Called on plugin unpause.
   100 	 *
   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.
   104 	 */
   105 	virtual bool Unpause(char *error, size_t maxlen)
   106 	{
   107 		return true;
   108 	}
   109 public:
   110 	/** @brief Return author as string */
   111 	virtual const char *GetAuthor() =0;
   112 
   113 	/** @brief Return plugin name as string */
   114 	virtual const char *GetName() =0;
   115 
   116 	/** @brief Return a description as string */
   117 	virtual const char *GetDescription() =0;
   118 
   119 	/** @brief Return a URL as string */
   120 	virtual const char *GetURL() =0;
   121 
   122 	/** @brief Return quick license code as string */
   123 	virtual const char *GetLicense() =0;
   124 
   125 	/** @brief Return version as string */
   126 	virtual const char *GetVersion() =0;
   127 
   128 	/** @brief Return author as string */
   129 	virtual const char *GetDate() =0;
   130 
   131 	/** @brief Return author as string */
   132 	virtual const char *GetLogTag() =0;
   133 public:
   134 	/**
   135 	 * @brief Called when all plugins have been loaded - API version 4
   136 	 *
   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(). 
   139 	 */
   140 	virtual void AllPluginsLoaded()
   141 	{
   142 	}
   143 };
   144 
   145 /**
   146  * @brief Added in 1.1 so plugins could listen to specific events
   147  */
   148 class IMetamodListener
   149 {
   150 public:
   151 	virtual ~IMetamodListener() { }
   152 public:
   153 	/**
   154 	 * @brief Called when a plugin is loaded.
   155 	 *
   156 	 * @param id		Id of the plugin.
   157 	 */
   158 	virtual void OnPluginLoad(PluginId id) { }
   159 
   160 	/**
   161 	 * @brief Called when a plugin is unloaded.
   162 	 *
   163 	 * @param id		Id of the plugin.
   164 	 */
   165 	virtual void OnPluginUnload(PluginId id) { }
   166 
   167 	/**
   168 	 * @brief Called when a plugin is paused.
   169 	 *
   170 	 * @param id		Id of the plugin.
   171 	 */
   172 	virtual void OnPluginPause(PluginId id) { }
   173 
   174 	/**
   175 	 * @brief Called when a plugin is unpaused.
   176 	 *
   177 	 * @param id		Id of the plugin.
   178 	 */
   179 	virtual void OnPluginUnpause(PluginId id) { }
   180 
   181 	/**
   182 	 * @brief Called when the level is loaded (after GameInit, before ServerActivate).
   183 	 *
   184 	 * To override this, hook IServerGameDLL::LevelInit().
   185 	 *
   186 	 * @param pMapName		Name of the map.
   187 	 * @param pMapEntities	Lump string of the map entities, in KeyValue format.
   188 	 * @param pOldLevel		Unknown.
   189 	 * @param pLandmarkName	Unknown.
   190 	 * @param loadGame		Unknown.
   191 	 * @param background	Unknown.
   192 	 */
   193 	virtual void OnLevelInit(char const *pMapName, char const *pMapEntities, char const *pOldLevel, char const *pLandmarkName, bool loadGame, bool background) { }
   194 
   195 	/**
   196 	 * @brief Called when the level is shut down.  May be called more than once.
   197 	 */
   198 	virtual void OnLevelShutdown() { }
   199 
   200 	/**
   201 	 * @brief Called when engineFactory() is used through Metamod:Source's wrapper.
   202 	 * This can be used to provide interfaces to other plugins or the GameDLL.
   203 	 *
   204 	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   205 	 *
   206 	 * @param iface			Interface string.
   207 	 * @param ret			Optional pointer to store return code.
   208 	 * @return				Generic pointer to the interface, or NULL if not found.
   209 	 */
   210 	virtual void *OnEngineQuery(const char *iface, int *ret)
   211 	{
   212 		if (ret)
   213 		{
   214 			*ret = IFACE_FAILED;
   215 		}
   216 
   217 		return NULL; 
   218 	}
   219 
   220 	/**
   221 	 * @brief Called when the physics factory is used through Metamod:Source's wrapper.
   222 	 * This can be used to provide interfaces to other plugins.
   223 	 *
   224 	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   225 	 *
   226 	 * @param iface			Interface string.
   227 	 * @param ret			Optional pointer to store return code.
   228 	 * @return				Generic pointer to the interface, or NULL if not found.
   229 	 */
   230 	virtual void *OnPhysicsQuery(const char *iface, int *ret)
   231 	{
   232 		if (ret)
   233 		{
   234 			*ret = IFACE_FAILED;
   235 		}
   236 
   237 		return NULL; 
   238 	}
   239 
   240 	/**
   241 	 * @brief Called when the filesystem factory is used through Metamod:Source's wrapper.
   242 	 * This can be used to provide interfaces to other plugins.
   243 	 *
   244 	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   245 	 *
   246 	 * @param iface			Interface string.
   247 	 * @param ret			Optional pointer to store return code.
   248 	 * @return				Generic pointer to the interface, or NULL if not found.
   249 	 */
   250 	virtual void *OnFileSystemQuery(const char *iface, int *ret)
   251 	{
   252 		if (ret)
   253 		{
   254 			*ret = IFACE_FAILED;
   255 		}
   256 		
   257 		return NULL; 
   258 	}
   259 
   260 	/**
   261 	 * @brief Called when the server DLL's factory is used through Metamod:Source's wrapper.
   262 	 * This can be used to provide interfaces to other plugins.
   263 	 *
   264 	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   265 	 *
   266 	 * @param iface			Interface string.
   267 	 * @param ret			Optional pointer to store return code.
   268 	 * @return				Generic pointer to the interface, or NULL if not found.
   269 	 */
   270 	virtual void *OnGameDLLQuery(const char *iface, int *ret)
   271 	{
   272 		if (ret)
   273 		{
   274 			*ret = IFACE_FAILED;
   275 		}
   276 
   277 		return NULL; 
   278 	}
   279 
   280 	/**
   281 	 * @brief Called when Metamod's own factory is invoked.  
   282 	 * This can be used to provide interfaces to other plugins.
   283 	 *
   284 	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   285 	 *
   286 	 * @param iface			Interface string.
   287 	 * @param ret			Optional pointer to store return code.
   288 	 * @return				Generic pointer to the interface, or NULL if not found.
   289 	 */
   290 	virtual void *OnMetamodQuery(const char *iface, int *ret)
   291 	{
   292 		if (ret)
   293 		{
   294 			*ret = IFACE_FAILED;
   295 		}
   296 
   297 		return NULL; 	
   298 	}
   299 
   300 	/**
   301 	 * @brief Called when Metamod:Source acquires a valid IServerPluginCallbacks 
   302 	 * pointer to be used for hooking by plugins.
   303 	 *
   304 	 * This will only be called after a call to ISmmAPI::EnableVSPListener().
   305 	 * If called before GameInit, this callback will occur before LevelInit.
   306 	 * Otherwise, it will be called on the first call after that.
   307 	 *
   308 	 * This callback is provided to all plugins regardless of which (or how many)
   309 	 * called EnableVSPListener(), but only if at least one did in fact enable it.
   310 	 *
   311 	 * This callback is only available for plugins using API v1:5 (SourceMM 1.4+).
   312 	 *
   313 	 * @param iface			Interface pointer.  If NULL, then the VSP listening construct
   314 	 *						failed to initialize and is not available.
   315 	 */
   316 	virtual void OnVSPListening(IServerPluginCallbacks *iface)
   317 	{
   318 	}
   319 };
   320 
   321 #define PL_EXPOSURE		CreateInterface
   322 #define PL_EXPOSURE_C	"CreateInterface"
   323 
   324 #define PLUGIN_EXPOSE(name, var) \
   325 	ISmmAPI *g_SMAPI = NULL; \
   326 	ISmmPlugin *g_PLAPI = NULL; \
   327 	PluginId g_PLID = (PluginId)0; \
   328 	SourceHook::ISourceHook *g_SHPtr = NULL; \
   329 	SMM_API void *PL_EXPOSURE(const char *name, int *code) { \
   330 		if (name && !strcmp(name, PLAPI_NAME)) { \
   331 			return static_cast<void *>(&var); \
   332 		} \
   333 		return NULL; \
   334 	}
   335 
   336 #define PLUGIN_GLOBALVARS()	\
   337 	extern SourceHook::ISourceHook *g_SHPtr; \
   338 	extern ISmmAPI *g_SMAPI; \
   339 	extern ISmmPlugin *g_PLAPI; \
   340 	extern PluginId g_PLID; 
   341 
   342 #define PLUGIN_SAVEVARS() \
   343 	g_SMAPI = ismm; \
   344 	g_SHPtr = static_cast<SourceHook::ISourceHook *>(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \
   345 	g_PLAPI = static_cast<ISmmPlugin *>(this); \
   346 	g_PLID = id;
   347 
   348 #define META_LOG				g_SMAPI->LogMsg
   349 #define META_REGCMD(name)		g_SMAPI->RegisterConCmdBase(g_PLAPI, name##_command)
   350 #define META_REGCVAR(var)		g_SMAPI->RegisterConCmdBase(g_PLAPI, var)
   351 #define META_UNREGCMD(name)		g_SMAPI->UnregisterConCmdBase(g_PLAPI, name##_command)
   352 #define META_UNREGCVAR(var)		g_SMAPI->UnregisterConCmdBase(g_PLAPI, var)
   353 #define	META_CONPRINT			g_SMAPI->ConPrint
   354 #define META_CONPRINTF			g_SMAPI->ConPrintf
   355 
   356 //probably should use this up above someday
   357 #define CONCMD_VARNAME(name) name##_command
   358 
   359 #if !defined SMM_API
   360 #if defined __WIN32__ || defined _WIN32 || defined WIN32
   361 	#define SMM_API extern "C" __declspec(dllexport)
   362 #elif defined __GNUC__
   363 	#if (__GNUC__ == 4) && (__GNUC_MINOR__ >= 1)
   364 		#define SMM_API extern "C" __attribute__ ((visibility("default")))	
   365 	#else
   366 		#define SMM_API	extern "C" 
   367 	#endif	
   368 #endif
   369 #endif //!defined SMM_API
   370 
   371 /**
   372  * @brief Macro for automatically getting a current or newer Valve interface.
   373  *
   374  * @param v_factory		Factory method to use from ISmmAPI (such as engineFactory).
   375  * @param v_var			Variable name to store into.
   376  * @param v_type		Interface type (do not include the pointer/asterisk).
   377  * @param v_name		Inteface name.
   378  */
   379 #define GET_V_IFACE_CURRENT(v_factory, v_var, v_type, v_name) \
   380 	v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name); \
   381 	if (!v_var) \
   382 	{ \
   383 		if (error && maxlen) \
   384 		{ \
   385 			snprintf(error, maxlen, "Could not find interface: %s", v_name); \
   386 		} \
   387 		return false; \
   388 	}
   389 
   390  /**
   391   * @brief Same as GET_V_IFACE, except searches for any.
   392   *
   393   * @param v_factory		Factory method to use from ISmmAPI (such as engineFactory).
   394   * @param v_var			Variable name to store into.
   395   * @param v_type		Interface type (do not include the pointer/asterisk).
   396   * @param v_name		Inteface name.
   397   */
   398 #define GET_V_IFACE_ANY(v_factory, v_var, v_type, v_name) \
   399 	v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name, 0); \
   400 	if (!v_var) \
   401 	{ \
   402 		if (error && maxlen) \
   403 		{ \
   404 			snprintf(error, maxlen, "Could not find interface: %s", v_name); \
   405 		} \
   406 		return false; \
   407 	}
   408 	
   409 
   410 #endif //_INCLUDE_ISMM_PLUGIN_H