sourcemm/ISmmPlugin.h
author David Anderson <dvander@alliedmods.net>
Sat Oct 06 16:47:58 2007 +0000 (2007-10-06)
changeset 376 f2d55f90f697
parent 375 17ca1d5645ac
child 396 ed81bca8944a
permissions -rw-r--r--
added format/formatargs api
     1 /**
     2  * vim: set ts=4 :
     3  * ======================================================
     4  * Metamod:Source
     5  * Copyright (C) 2004-2007 AlliedModders LLC and authors.
     6  * All rights reserved.
     7  * ======================================================
     8  *
     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.
    12  * 
    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:
    16  *
    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.
    24  *
    25  * Version: $Id$
    26  */
    27 
    28 #ifndef _INCLUDE_ISMM_PLUGIN_H
    29 #define _INCLUDE_ISMM_PLUGIN_H
    30 
    31 /**
    32  * @brief Plugin API interface
    33  * @file ISmmPlugin.h
    34  */
    35 
    36 #include <interface.h>
    37 #include <sourcehook.h>
    38 #include "ISmmAPI.h"
    39 
    40 #define PLAPI_VERSION	13
    41 #define PLAPI_NAME		"ISmmPlugin"
    42 
    43 class ISmmAPI;
    44 
    45 class ISmmPlugin
    46 {
    47 public:
    48 	virtual int GetApiVersion() { return PLAPI_VERSION; }
    49 	virtual ~ISmmPlugin() { }
    50 public:
    51 	/**
    52 	 * @brief Called on plugin load.
    53 	 *
    54 	 * NOTE - As of API 7, this is called as DLLInit() executes - after the parameters are known, but before 
    55 	 *  the original GameDLL function is called.  Therefore, you cannot hook it, but you don't need to - 
    56 	 *  Load() is basically your hook.
    57 	 * NOTE - As of API 7, you can override factories before the engine and gamedll exchange them.
    58 	 *  However, take care to note that if your plugin is unloaded, and the gamedll/engine have cached
    59 	 *  an interface you've passed, something will definitely crash.  Be careful.
    60 	 *
    61 	 * @param id		Internal id of plugin.  Saved globally by PLUGIN_SAVEVARS()
    62 	 * @param ismm		External API for SourceMM.  Saved globally by PLUGIN_SAVEVARS()
    63 	 * @param list		Contains a list of factories.  Hook a factory call by setting one equal to your own function.
    64 	 * @param late		Set to true if your plugin was loaded late (not at server load).
    65 	 * @param error		Error message buffer
    66 	 * @param maxlen	Size of error message buffer
    67 	 * @return			True if successful, return false to reject the load.
    68 	 */
    69 	virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0;
    70 
    71 	/**
    72 	 * @brief Called when your plugin is "queried".  
    73 	 * 
    74 	 * This is useful for rejecting a loaded state.  For example, if your plugin wants 
    75 	 * to stop operating, it can simply return false and copy an error message.  This 
    76 	 * will notify other plugins or MM:S of something bad that happened.  NOTE - MM:S 
    77 	 * will not cache the return state, so if you return false,  your plugin will not 
    78 	 * actually be paused or unloaded.  This callback will be called when:
    79 	 *  - Another plugin requests it
    80 	 *  - Someone types "meta list", it will show up as "REFUSED"
    81 	 *  - When Metamod need to re-check the plugin's status
    82 	 *  - If the plugin does something like overload a factory, Metamod will make sure the Query() returns true
    83 	 *    before calling it.
    84 	 *  Also note that this query will only override Metamod when the plugin is running and not paused.
    85 	 *
    86 	 * @param error		Buffer for error message.  This can be NULL!
    87 	 * @param maxlen	Maximum length of error buffer.
    88 	 * @return			Status code - true for okay, false for badness.
    89 	 */
    90 	virtual bool QueryRunning(char *error, size_t maxlen)
    91 	{
    92 		return true;
    93 	}
    94 
    95 	/** 
    96 	 * @brief Called on plugin unload.  You can return false if you know your plugin
    97 	 *  is not capable of restoring critical states it modifies.
    98 	 *
    99 	 * @param error		Error message buffer
   100 	 * @param maxlen	Size of error message buffer
   101 	 * @return			True on success, return false to request no unload.
   102 	 */
   103 	virtual bool Unload(char *error, size_t maxlen)
   104 	{
   105 		return true;
   106 	}
   107 
   108 	/** @brief Called on plugin pause.
   109 	 *
   110 	 * @param	error Error message buffer
   111 	 * @param	maxlen Size of error message buffer
   112 	 * @return	True on success, return false to request no pause.
   113 	 */
   114 	virtual bool Pause(char *error, size_t maxlen)
   115 	{
   116 		return true;
   117 	}
   118 
   119 	/** @brief Called on plugin unpause.
   120 	 *
   121 	 * @param	error Error message buffer
   122 	 * @param	maxlen Size of error message buffer
   123 	 * @return	True on success, return false to request no unpause.
   124 	 */
   125 	virtual bool Unpause(char *error, size_t maxlen)
   126 	{
   127 		return true;
   128 	}
   129 public:
   130 	/** @brief Return author as string */
   131 	virtual const char *GetAuthor() =0;
   132 
   133 	/** @brief Return plugin name as string */
   134 	virtual const char *GetName() =0;
   135 
   136 	/** @brief Return a description as string */
   137 	virtual const char *GetDescription() =0;
   138 
   139 	/** @brief Return a URL as string */
   140 	virtual const char *GetURL() =0;
   141 
   142 	/** @brief Return quick license code as string */
   143 	virtual const char *GetLicense() =0;
   144 
   145 	/** @brief Return version as string */
   146 	virtual const char *GetVersion() =0;
   147 
   148 	/** @brief Return author as string */
   149 	virtual const char *GetDate() =0;
   150 
   151 	/** @brief Return author as string */
   152 	virtual const char *GetLogTag() =0;
   153 public:
   154 	/**
   155 	 * @brief Called when all plugins have been loaded.  
   156 	 *
   157 	 * This is called after DLLInit(), and thus the mod has been mostly initialized. 
   158 	 * It is also safe to assume that all other (automatically loaded) plugins are now 
   159 	 * ready to start interacting, because they are all loaded.
   160 	 */
   161 	virtual void AllPluginsLoaded()
   162 	{
   163 	}
   164 };
   165 
   166 /**
   167  * @brief Added in 1.1 so plugins could listen to specific events
   168  */
   169 class IMetamodListener
   170 {
   171 public:
   172 	virtual ~IMetamodListener()
   173 	{
   174 	}
   175 public:
   176 	/**
   177 	 * @brief Called when a plugin is loaded.
   178 	 *
   179 	 * @param id		Id of the plugin.
   180 	 */
   181 	virtual void OnPluginLoad(PluginId id)
   182 	{
   183 	}
   184 
   185 	/**
   186 	 * @brief Called when a plugin is unloaded.
   187 	 *
   188 	 * @param id		Id of the plugin.
   189 	 */
   190 	virtual void OnPluginUnload(PluginId id)
   191 	{
   192 	}
   193 
   194 	/**
   195 	 * @brief Called when a plugin is paused.
   196 	 *
   197 	 * @param id		Id of the plugin.
   198 	 */
   199 	virtual void OnPluginPause(PluginId id)
   200 	{
   201 	}
   202 
   203 	/**
   204 	 * @brief Called when a plugin is unpaused.
   205 	 *
   206 	 * @param id		Id of the plugin.
   207 	 */
   208 	virtual void OnPluginUnpause(PluginId id)
   209 	{
   210 	}
   211 
   212 	/**
   213 	 * @brief Called when the level is loaded (after GameInit, before ServerActivate).
   214 	 *
   215 	 * To override this, hook IServerGameDLL::LevelInit().
   216 	 *
   217 	 * @param pMapName		Name of the map.
   218 	 * @param pMapEntities	Lump string of the map entities, in KeyValue format.
   219 	 * @param pOldLevel		Unknown.
   220 	 * @param pLandmarkName	Unknown.
   221 	 * @param loadGame		Unknown.
   222 	 * @param background	Unknown.
   223 	 */
   224 	virtual void OnLevelInit(char const *pMapName, char const *pMapEntities, char const *pOldLevel, char const *pLandmarkName, bool loadGame, bool background) { }
   225 
   226 	/**
   227 	 * @brief Called when the level is shut down.  May be called more than once.
   228 	 */
   229 	virtual void OnLevelShutdown()
   230 	{
   231 	}
   232 
   233 	/**
   234 	 * @brief Called when engineFactory() is used through Metamod:Source's wrapper.
   235 	 * This can be used to provide interfaces to other plugins or the GameDLL.
   236 	 *
   237 	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   238 	 *
   239 	 * @param iface			Interface string.
   240 	 * @param ret			Optional pointer to store return code.
   241 	 * @return				Generic pointer to the interface, or NULL if not found.
   242 	 */
   243 	virtual void *OnEngineQuery(const char *iface, int *ret)
   244 	{
   245 		if (ret)
   246 		{
   247 			*ret = IFACE_FAILED;
   248 		}
   249 
   250 		return NULL; 
   251 	}
   252 
   253 	/**
   254 	 * @brief Called when the physics factory is used through Metamod:Source's wrapper.
   255 	 * This can be used to provide interfaces to other plugins.
   256 	 *
   257 	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   258 	 *
   259 	 * @param iface			Interface string.
   260 	 * @param ret			Optional pointer to store return code.
   261 	 * @return				Generic pointer to the interface, or NULL if not found.
   262 	 */
   263 	virtual void *OnPhysicsQuery(const char *iface, int *ret)
   264 	{
   265 		if (ret)
   266 		{
   267 			*ret = IFACE_FAILED;
   268 		}
   269 
   270 		return NULL; 
   271 	}
   272 
   273 	/**
   274 	 * @brief Called when the filesystem factory is used through Metamod:Source's wrapper.
   275 	 * This can be used to provide interfaces to other plugins.
   276 	 *
   277 	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   278 	 *
   279 	 * @param iface			Interface string.
   280 	 * @param ret			Optional pointer to store return code.
   281 	 * @return				Generic pointer to the interface, or NULL if not found.
   282 	 */
   283 	virtual void *OnFileSystemQuery(const char *iface, int *ret)
   284 	{
   285 		if (ret)
   286 		{
   287 			*ret = IFACE_FAILED;
   288 		}
   289 		
   290 		return NULL; 
   291 	}
   292 
   293 	/**
   294 	 * @brief Called when the server DLL's factory is used through Metamod:Source's wrapper.
   295 	 * This can be used to provide interfaces to other plugins.
   296 	 *
   297 	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   298 	 *
   299 	 * @param iface			Interface string.
   300 	 * @param ret			Optional pointer to store return code.
   301 	 * @return				Generic pointer to the interface, or NULL if not found.
   302 	 */
   303 	virtual void *OnGameDLLQuery(const char *iface, int *ret)
   304 	{
   305 		if (ret)
   306 		{
   307 			*ret = IFACE_FAILED;
   308 		}
   309 
   310 		return NULL; 
   311 	}
   312 
   313 	/**
   314 	 * @brief Called when Metamod's own factory is invoked.  
   315 	 * This can be used to provide interfaces to other plugins.
   316 	 *
   317 	 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   318 	 *
   319 	 * @param iface			Interface string.
   320 	 * @param ret			Optional pointer to store return code.
   321 	 * @return				Generic pointer to the interface, or NULL if not found.
   322 	 */
   323 	virtual void *OnMetamodQuery(const char *iface, int *ret)
   324 	{
   325 		if (ret)
   326 		{
   327 			*ret = IFACE_FAILED;
   328 		}
   329 
   330 		return NULL; 	
   331 	}
   332 
   333 	/**
   334 	 * @brief Called when Metamod:Source acquires a valid IServerPluginCallbacks 
   335 	 * pointer to be used for hooking by plugins.
   336 	 *
   337 	 * This will only be called after a call to ISmmAPI::EnableVSPListener().
   338 	 * If called before GameInit, this callback will occur before LevelInit.
   339 	 * Otherwise, it will be called on the first call after that.
   340 	 *
   341 	 * This callback is provided to all plugins regardless of which (or how many)
   342 	 * called EnableVSPListener(), but only if at least one did in fact enable it.
   343 	 *
   344 	 * This callback is only available for plugins using API v1:5 (Metamod:Source 1.4+).
   345 	 * If a plugin loads lately, it may still call EnableVSPListener().
   346 	 *
   347 	 * @param iface			Interface pointer.  If NULL, then the VSP listening construct
   348 	 *						failed to initialize and is not available.
   349 	 */
   350 	virtual void OnVSPListening(IServerPluginCallbacks *iface) { }
   351 
   352 	/**
   353 	 * @brief Called when Metamod:Source is about to remove a concommand or convar.
   354 	 * This can also be called if ISmmAPI::UnregisterConCmdBase is used by a plugin.
   355 	 *
   356 	 * @param id			Id of the plugin that created the concommand or convar.
   357 	 * @param pCommand		Pointer to concommand or convar that is being removed.
   358 	 */
   359 	virtual void OnUnlinkConCommandBase(PluginId id, ConCommandBase *pCommand)
   360 	{
   361 	}
   362 };
   363 
   364 #define PL_EXPOSURE		CreateInterface
   365 #define PL_EXPOSURE_C	"CreateInterface"
   366 
   367 #define PLUGIN_EXPOSE(name, var) \
   368 	ISmmAPI *g_SMAPI = NULL; \
   369 	ISmmPlugin *g_PLAPI = NULL; \
   370 	PluginId g_PLID = (PluginId)0; \
   371 	SourceHook::ISourceHook *g_SHPtr = NULL; \
   372 	SMM_API void *PL_EXPOSURE(const char *name, int *code) { \
   373 		if (name && !strcmp(name, PLAPI_NAME)) { \
   374 			return static_cast<void *>(&var); \
   375 		} \
   376 		return NULL; \
   377 	}
   378 
   379 #define PLUGIN_GLOBALVARS()	\
   380 	extern SourceHook::ISourceHook *g_SHPtr; \
   381 	extern ISmmAPI *g_SMAPI; \
   382 	extern ISmmPlugin *g_PLAPI; \
   383 	extern PluginId g_PLID; 
   384 
   385 #define PLUGIN_SAVEVARS() \
   386 	g_SMAPI = ismm; \
   387 	g_SHPtr = static_cast<SourceHook::ISourceHook *>(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \
   388 	g_PLAPI = static_cast<ISmmPlugin *>(this); \
   389 	g_PLID = id;
   390 
   391 #define META_LOG				g_SMAPI->LogMsg
   392 #define META_REGCMD(name)		g_SMAPI->RegisterConCommandBase(g_PLAPI, name##_command)
   393 #define META_REGCVAR(var)		g_SMAPI->RegisterConCommandBase(g_PLAPI, var)
   394 #define META_UNREGCMD(name)		g_SMAPI->UnregisterConCommandBase(g_PLAPI, name##_command)
   395 #define META_UNREGCVAR(var)		g_SMAPI->UnregisterConCommandBase(g_PLAPI, var)
   396 #define	META_CONPRINT			g_SMAPI->ConPrint
   397 #define META_CONPRINTF			g_SMAPI->ConPrintf
   398 
   399 /* Probably should use this up above someday */
   400 #define CONCMD_VARNAME(name) name##_command
   401 
   402 #if !defined SMM_API
   403 #if defined __WIN32__ || defined _WIN32 || defined WIN32
   404 	#define SMM_API extern "C" __declspec(dllexport)
   405 #elif defined __GNUC__
   406 	#if (__GNUC__ == 4) && (__GNUC_MINOR__ >= 1)
   407 		#define SMM_API extern "C" __attribute__ ((visibility("default")))	
   408 	#else
   409 		#define SMM_API	extern "C" 
   410 	#endif	
   411 #endif
   412 #endif //!defined SMM_API
   413 
   414 /**
   415  * @brief Macro for automatically getting a current or newer Valve interface.
   416  *
   417  * @param v_factory		Factory method to use from ISmmAPI (such as engineFactory).
   418  * @param v_var			Variable name to store into.
   419  * @param v_type		Interface type (do not include the pointer/asterisk).
   420  * @param v_name		Interface name.
   421  */
   422 #define GET_V_IFACE_CURRENT(v_factory, v_var, v_type, v_name) \
   423 	v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name); \
   424 	if (!v_var) \
   425 	{ \
   426 		if (error && maxlen) \
   427 		{ \
   428 			ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
   429 		} \
   430 		return false; \
   431 	}
   432 
   433  /**
   434   * @brief Same as GET_V_IFACE, except searches for any.
   435   *
   436   * @param v_factory	Factory method to use from ISmmAPI (such as engineFactory).
   437   * @param v_var		Variable name to store into.
   438   * @param v_type		Interface type (do not include the pointer/asterisk).
   439   * @param v_name		Interface name.
   440   */
   441 #define GET_V_IFACE_ANY(v_factory, v_var, v_type, v_name) \
   442 	v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name, 0); \
   443 	if (!v_var) \
   444 	{ \
   445 		if (error && maxlen) \
   446 		{ \
   447 			ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
   448 		} \
   449 		return false; \
   450 	}
   451 
   452 #endif //_INCLUDE_ISMM_PLUGIN_H
   453