core/ISmmPlugin.h
author Nicholas Hastings <skamonkey@gmail.com>
Wed May 21 17:26:09 2014 -0400 (2014-05-21)
changeset 917 95639ee45d3d
parent 790 276192fd70a1
permissions -rw-r--r--
Trigger build for hl2sdk-l4d changes.
     1 /*
     2  * vim: set ts=4 :
     3  * ======================================================
     4  * Metamod:Source
     5  * Copyright (C) 2004-2008 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 These are callbacks that plugins can implement without hooks.
    34  * The pure-virtual ISmmPlugin callbacks must be implemented for the load to load.
    35  */
    36 
    37 #include <sourcehook.h>
    38 #include <IPluginManager.h>
    39 #include <ISmmAPI.h>
    40 #include <ISmmPluginExt.h>
    41 
    42 namespace SourceMM
    43 {
    44 	class ISmmAPI;
    45 
    46 	/**
    47 	 * @brief Callbacks that a plugin must expose.
    48 	 */
    49 	class ISmmPlugin
    50 	{
    51 	public:
    52 		/**
    53 		 * @brief Called to request the plugin's API version.
    54 		 *
    55 		 * This is the first callback invoked, and always remains at the top 
    56 		 * of the virtual table.  
    57 		 *
    58 		 * @return			Plugin API version.
    59 		 */
    60 		virtual int GetApiVersion() 
    61 		{ 
    62 			return METAMOD_PLAPI_VERSION; 
    63 		}
    64 
    65 		/**
    66 		 * @brief Virtual destructor so GCC doesn't complain.
    67 		 */
    68 		virtual ~ISmmPlugin()
    69 		{
    70 		}
    71 
    72 	public:
    73 		/**
    74 		 * @brief Called on plugin load.
    75 		 *
    76 		 * This is called as DLLInit() executes - after the parameters are 
    77 		 * known, but before the original GameDLL function is called.  
    78 		 * Therefore, you cannot hook it, but you don't need to - Load() is 
    79 		 * basically your hook.  You can override factories before the engine 
    80 		 * and gamedll exchange them.  However, take care to note that if your 
    81 		 * plugin is unloaded, and the gamedll/engine have cached an interface 
    82 		 * you've passed, something will definitely crash.  Be careful.
    83 		 *
    84 		 * @param id		Internal id of plugin.  Saved globally by PLUGIN_SAVEVARS()
    85 		 * @param ismm		External API for SourceMM.  Saved globally by PLUGIN_SAVEVARS()
    86 		 * @param error		Error message buffer
    87 		 * @param maxlength	Size of error message buffer
    88 		 * @param late		Set to true if your plugin was loaded late (not at server load).
    89 		 * @return			True if successful, return false to reject the load.
    90 		 */
    91 		virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0;
    92 
    93 		/**
    94 		 * @brief Called when all plugins have been loaded.  
    95 		 *
    96 		 * This is called after DLLInit(), and thus the mod has been mostly initialized. 
    97 		 * It is also safe to assume that all other (automatically loaded) plugins are now 
    98 		 * ready to start interacting, because they are all loaded.
    99 		 */
   100 		virtual void AllPluginsLoaded()
   101 		{
   102 		}
   103 
   104 		/**
   105 		 * @brief Called when your plugin is "queried".  
   106 		 * 
   107 		 * This is useful for rejecting a loaded state.  For example, if your 
   108 		 * plugin wants to stop operating, it can simply return false and copy 
   109 		 * an error message.  This will notify other plugins or MM:S of 
   110 		 * something bad that happened.  MM:S will not cache the return state, 
   111 		 * so if you return false,  your plugin will not actually be paused or 
   112 		 * unloaded.  This callback will be called when:
   113 		 *  - Another plugin requests it
   114 		 *  - Someone types "meta list", it will show up as "REFUSED"
   115 		 *  - When Metamod need to re-check the plugin's status
   116 		 *  - If the plugin does something like overload a factory, Metamod 
   117 		 *    will make sure the Query() returns true before calling it.
   118 		 *  Also note that this query will only override Metamod when the 
   119 		 *  plugin is running and not paused.
   120 		 *
   121 		 * @param error		Buffer for error message, or NULL if none.
   122 		 * @param maxlen	Maximum length of error buffer.
   123 		 * @return			Status code - true for okay, false for badness.
   124 		 */
   125 		virtual bool QueryRunning(char *error, size_t maxlen)
   126 		{
   127 			return true;
   128 		}
   129 
   130 		/** 
   131 		 * @brief Called on plugin unload.  You can return false if you know 
   132 		 * your plugin is not capable of restoring critical states it modifies.
   133 		 *
   134 		 * @param error		Error message buffer
   135 		 * @param maxlen	Size of error message buffer
   136 		 * @return			True on success, return false to request no unload.
   137 		 */
   138 		virtual bool Unload(char *error, size_t maxlen)
   139 		{
   140 			return true;
   141 		}
   142 
   143 		/** 
   144 		 * @brief Called on plugin pause.
   145 		 *
   146 		 * @param	error Error message buffer
   147 		 * @param	maxlen Size of error message buffer
   148 		 * @return	True on success, return false to request no pause.
   149 		 */
   150 		virtual bool Pause(char *error, size_t maxlen)
   151 		{
   152 			return true;
   153 		}
   154 
   155 		/** 
   156 		 * @brief Called on plugin unpause.
   157 		 *
   158 		 * @param	error Error message buffer
   159 		 * @param	maxlen Size of error message buffer
   160 		 * @return	True on success, return false to request no unpause.
   161 		 */
   162 		virtual bool Unpause(char *error, size_t maxlen)
   163 		{
   164 			return true;
   165 		}
   166 	public:
   167 		/** @brief Return author as string */
   168 		virtual const char *GetAuthor() =0;
   169 	
   170 		/** @brief Return plugin name as string */
   171 		virtual const char *GetName() =0;
   172 	
   173 		/** @brief Return a description as string */
   174 		virtual const char *GetDescription() =0;
   175 	
   176 		/** @brief Return a URL as string */
   177 		virtual const char *GetURL() =0;
   178 	
   179 		/** @brief Return quick license code as string */
   180 		virtual const char *GetLicense() =0;
   181 	
   182 		/** @brief Return version as string */
   183 		virtual const char *GetVersion() =0;
   184 	
   185 		/** @brief Return author as string */
   186 		virtual const char *GetDate() =0;
   187 	
   188 		/** @brief Return author as string */
   189 		virtual const char *GetLogTag() =0;
   190 	};
   191 
   192 	/**
   193 	 * @brief Various events that Metamod can fire.
   194 	 */
   195 	class IMetamodListener
   196 	{
   197 	public:
   198 		/**
   199 		 * @brief Called when a plugin is loaded.
   200 		 *
   201 		 * @param id		Id of the plugin.
   202 		 */
   203 		virtual void OnPluginLoad(PluginId id)
   204 		{
   205 		}
   206 
   207 		/**
   208 		 * @brief Called when a plugin is unloaded.
   209 		 *
   210 		 * @param id		Id of the plugin.
   211 		 */
   212 		virtual void OnPluginUnload(PluginId id)
   213 		{
   214 		}
   215 	
   216 		/**
   217 		 * @brief Called when a plugin is paused.
   218 		 *
   219 		 * @param id		Id of the plugin.
   220 		 */
   221 		virtual void OnPluginPause(PluginId id)
   222 		{
   223 		}
   224 	
   225 		/**
   226 		 * @brief Called when a plugin is unpaused.
   227 		 *
   228 		 * @param id		Id of the plugin.
   229 		 */
   230 		virtual void OnPluginUnpause(PluginId id)
   231 		{
   232 		}
   233 	
   234 		/**
   235 		 * @brief Called when the level is loaded (after GameInit, before 
   236 		 * ServerActivate).
   237 		 *
   238 		 * To override this, hook IServerGameDLL::LevelInit().
   239 		 *
   240 		 * @param pMapName		Name of the map.
   241 		 * @param pMapEntities	Lump string of the map entities, in KeyValues
   242 		 * 						format.
   243 		 * @param pOldLevel		Unknown.
   244 		 * @param pLandmarkName	Unknown.
   245 		 * @param loadGame		Unknown.
   246 		 * @param background	Unknown.
   247 		 */
   248 		virtual void OnLevelInit(char const *pMapName, 
   249 								 char const *pMapEntities, 
   250 								 char const *pOldLevel, 
   251 								 char const *pLandmarkName, 
   252 								 bool loadGame, 
   253 								 bool background) 
   254 		{ 
   255 		}
   256 
   257 		/**
   258 		 * @brief Called when the level is shut down.  May be called more than 
   259 		 * once.
   260 		 */
   261 		virtual void OnLevelShutdown()
   262 		{
   263 		}
   264 
   265 		/**
   266 		 * @brief Called when engineFactory() is used through Metamod:Source's 
   267 		 * wrapper.  This can be used to provide interfaces to other plugins or
   268 		 * the GameDLL.
   269 		 *
   270 		 * If ret is passed, you should fill it with META_IFACE_OK or META_IFACE_FAILED.
   271 		 *
   272 		 * @param iface			Interface string.
   273 		 * @param ret			Optional pointer to store return code.
   274 		 * @return				Generic pointer to the interface, or NULL if 
   275 		 * 						not found.
   276 		 */
   277 		virtual void *OnEngineQuery(const char *iface, int *ret)
   278 		{
   279 			if (ret)
   280 			{
   281 				*ret = META_IFACE_FAILED;
   282 			}
   283 
   284 			return NULL; 
   285 		}
   286 
   287 		/**
   288 		 * @brief Called when the physics factory is used through 
   289 		 * Metamod:Source's wrapper. This can be used to provide interfaces to 
   290 		 * other plugins.
   291 		 *
   292 		 * If ret is passed, you should fill it with META_IFACE_OK or META_IFACE_FAILED.
   293 		 *
   294 		 * @param iface			Interface string.
   295 		 * @param ret			Optional pointer to store return code.
   296 		 * @return				Generic pointer to the interface, or NULL if 
   297 		 * 						not found.
   298 		 */
   299 		virtual void *OnPhysicsQuery(const char *iface, int *ret)
   300 		{
   301 			if (ret)
   302 			{
   303 				*ret = META_IFACE_FAILED;
   304 			}
   305 	
   306 			return NULL; 
   307 		}
   308 
   309 		/**
   310 		 * @brief Called when the filesystem factory is used through 
   311 		 * Metamod:Source's wrapper.  This can be used to provide interfaces to 
   312 		 * other plugins.
   313 		 *
   314 		 * If ret is passed, you should fill it with META_IFACE_OK or META_IFACE_FAILED.
   315 		 *
   316 		 * @param iface			Interface string.
   317 		 * @param ret			Optional pointer to store return code.
   318 		 * @return				Generic pointer to the interface, or NULL if not 
   319 		 * 						found.
   320 		 */
   321 		virtual void *OnFileSystemQuery(const char *iface, int *ret)
   322 		{
   323 			if (ret)
   324 			{
   325 				*ret = META_IFACE_FAILED;
   326 			}
   327 			
   328 			return NULL; 
   329 		}
   330 
   331 		/**
   332 		 * @brief Called when the server DLL's factory is used through 
   333 		 * Metamod:Source's wrapper.  This can be used to provide interfaces to 
   334 		 * other plugins.
   335 		 *
   336 		 * If ret is passed, you should fill it with META_IFACE_OK or META_IFACE_FAILED.
   337 		 *
   338 		 * @param iface			Interface string.
   339 		 * @param ret			Optional pointer to store return code.
   340 		 * @return				Generic pointer to the interface, or NULL if not 
   341 		 * 						found.
   342 		 */
   343 		virtual void *OnGameDLLQuery(const char *iface, int *ret)
   344 		{
   345 			if (ret)
   346 			{
   347 				*ret = META_IFACE_FAILED;
   348 			}
   349 	
   350 			return NULL; 
   351 		}
   352 
   353 		/**
   354 		 * @brief Called when Metamod's own factory is invoked.  
   355 		 * This can be used to provide interfaces to other plugins.
   356 		 *
   357 		 * If ret is passed, you should fill it with META_IFACE_OK or META_IFACE_FAILED.
   358 		 *
   359 		 * @param iface			Interface string.
   360 		 * @param ret			Optional pointer to store return code.
   361 		 * @return				Generic pointer to the interface, or NULL if not 
   362 		 * 						found.
   363 		 */
   364 		virtual void *OnMetamodQuery(const char *iface, int *ret)
   365 		{
   366 			if (ret)
   367 			{
   368 				*ret = META_IFACE_FAILED;
   369 			}
   370 	
   371 			return NULL; 	
   372 		}
   373 
   374 		/**
   375 		 * @brief Called when Metamod:Source acquires a valid 
   376 		 * IServerPluginCallbacks pointer to be used for hooking by plugins.
   377 		 *
   378 		 * This will only be called after a call to ISmmAPI::EnableVSPListener().
   379 		 * If called before GameInit, this callback will occur before LevelInit.
   380 		 * Otherwise, it will be called on the first call after that.
   381 		 *
   382 		 * This callback is provided to all plugins regardless of which (or how 
   383 		 * many) called EnableVSPListener(), but only if at least one did in 
   384 		 * fact enable it, and only once for all plugins.  That is, a late 
   385 		 * loading plugin should use ISmmAPI::GetVSPInfo() before relying on 
   386 		 * this callback.
   387 		 *
   388 		 * This callback is never called if Metamod:Source is in VSP mode.  
   389 		 * If in VSP mode, a VSP instance is automatically and always available 
   390 		 * via ISmmAPI::GetVSPInfo(), which should be called anyway (to handle 
   391 		 * late loading cases).
   392 		 *
   393 		 * @param iface			Interface pointer.  If NULL, then the VSP 
   394 		 * 						listening construct failed to initialize and 
   395 		 * 						is not available.
   396 		 */
   397 		virtual void OnVSPListening(IServerPluginCallbacks *iface) 
   398 		{ 
   399 		}
   400 
   401 		/**
   402 		 * @brief Called when Metamod:Source is about to remove a concommand or 
   403 		 * convar.  This can also be called if ISmmAPI::UnregisterConCmdBase is 
   404 		 * used by a plugin.
   405 		 *
   406 		 * @param id			Id of the plugin that created the concommand or 
   407 		 * 						convar.
   408 		 * @param pCommand		Pointer to concommand or convar that is being 
   409 		 * 						removed.
   410 		 */
   411 		virtual void OnUnlinkConCommandBase(PluginId id, ConCommandBase *pCommand)
   412 		{
   413 		}
   414 	};
   415 }
   416 
   417 #if !defined METAMOD_NO_AUTO_NAMESPACE
   418 using namespace SourceMM;
   419 #endif
   420 
   421 #define PL_EXPOSURE		CreateInterface
   422 #define PL_EXPOSURE_C	"CreateInterface"
   423 
   424 /**
   425  * @brief Exposes the plugin to the MM:S loader.
   426  *
   427  * @param name		Deprecated - should be a variable name (like name).
   428  * @param var		Name of the variable that contains the singleton.
   429  *					This macro automatically takes the address of it, so 
   430  * 					you should not pass a pointer to your plugin's 
   431  *					singleton.
   432  */
   433 #define PLUGIN_EXPOSE(name, var) \
   434 	ISmmAPI *g_SMAPI = NULL; \
   435 	ISmmPlugin *g_PLAPI = NULL; \
   436 	PluginId g_PLID = (PluginId)0; \
   437 	SourceHook::ISourceHook *g_SHPtr = NULL; \
   438 	SMM_API void *PL_EXPOSURE(const char *name, int *code) { \
   439 		if (name && !strcmp(name, METAMOD_PLAPI_NAME)) { \
   440 			return static_cast<void *>(&var); \
   441 		} \
   442 		return NULL; \
   443 	}
   444 
   445 
   446 /**
   447  * @brief This should be in one of your header files, if you wish 
   448  * to use values like g_SHPtr in other files.
   449  */
   450 #define PLUGIN_GLOBALVARS()	\
   451 	extern SourceHook::ISourceHook *g_SHPtr; \
   452 	extern ISmmAPI *g_SMAPI; \
   453 	extern ISmmPlugin *g_PLAPI; \
   454 	extern PluginId g_PLID; 
   455 
   456 /**
   457  * @brief This should be the first line in your Load callback.
   458  */
   459 #define PLUGIN_SAVEVARS() \
   460 	g_SMAPI = ismm; \
   461 	g_SHPtr = static_cast<SourceHook::ISourceHook *>(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \
   462 	g_PLAPI = static_cast<ISmmPlugin *>(this); \
   463 	g_PLID = id;
   464 
   465 #define META_LOG				g_SMAPI->LogMsg
   466 #define META_REGCMD(name)		g_SMAPI->RegisterConCommandBase(g_PLAPI, name##_command)
   467 #define META_REGCVAR(var)		g_SMAPI->RegisterConCommandBase(g_PLAPI, var)
   468 #define META_UNREGCMD(name)		g_SMAPI->UnregisterConCommandBase(g_PLAPI, name##_command)
   469 #define META_UNREGCVAR(var)		g_SMAPI->UnregisterConCommandBase(g_PLAPI, var)
   470 #define	META_CONPRINT			g_SMAPI->ConPrint
   471 #define META_CONPRINTF			g_SMAPI->ConPrintf
   472 
   473 /* Probably should use this up above someday */
   474 #define CONCMD_VARNAME(name) name##_command
   475 
   476 #if !defined SMM_API
   477 #if defined __WIN32__ || defined _WIN32 || defined WIN32
   478 	#define SMM_API extern "C" __declspec(dllexport)
   479 #elif defined __GNUC__
   480 	#if (__GNUC__ == 4) && (__GNUC_MINOR__ >= 1)
   481 		#define SMM_API extern "C" __attribute__ ((visibility("default")))	
   482 	#else
   483 		#define SMM_API	extern "C" 
   484 	#endif	
   485 #endif
   486 #endif //!defined SMM_API
   487 
   488 /**
   489  * @brief Macro for automatically getting a current or newer Valve interface.
   490  *
   491  * @param v_factory		Factory method to use from ISmmAPI (such as engineFactory).
   492  * @param v_var			Variable name to store into.
   493  * @param v_type		Interface type (do not include the pointer/asterisk).
   494  * @param v_name		Interface name.
   495  */
   496 #define GET_V_IFACE_CURRENT(v_factory, v_var, v_type, v_name) \
   497 	v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name); \
   498 	if (!v_var) \
   499 	{ \
   500 		if (error && maxlen) \
   501 		{ \
   502 			ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
   503 		} \
   504 		return false; \
   505 	}
   506 
   507  /**
   508   * @brief Same as GET_V_IFACE, except searches for any.
   509   *
   510   * @param v_factory	Factory method to use from ISmmAPI (such as engineFactory).
   511   * @param v_var		Variable name to store into.
   512   * @param v_type		Interface type (do not include the pointer/asterisk).
   513   * @param v_name		Interface name.
   514   */
   515 #define GET_V_IFACE_ANY(v_factory, v_var, v_type, v_name) \
   516 	v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name, 0); \
   517 	if (!v_var) \
   518 	{ \
   519 		if (error && maxlen) \
   520 		{ \
   521 			ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
   522 		} \
   523 		return false; \
   524 	}
   525 
   526 #endif //_INCLUDE_ISMM_PLUGIN_H
   527